Core architectural rules, coding conventions, and tech stack guidelines for the Dog-Love Frontend. Reference this for all frontend code changes.
pnpm dev # 개발 서버 (http://localhost:3000)
pnpm build # 프로덕션 빌드
pnpm lint # ESLint 검사
pnpm typecheck # TypeScript 타입 검사 (tsc --noEmit)
pnpm format:check # Prettier 포맷 검사
pnpm format:fix # Prettier 자동 수정
pnpm test # vitest 유닛 테스트
pnpm test:watch # vitest watch 모드
pnpm test:coverage # 커버리지 포함 테스트 (70% 임계값)
pnpm test:e2e # Playwright E2E 테스트
pnpm validate # 전체 검증 (lint + typecheck + test + build)
feat: 새로운 기능fix: 버그 수정refactor: 리팩토링style: 스타일/포맷 변경docs: 문서chore: 설정 및 기타PascalCase named export (export function MyComponent)camelCase named export@/* (프로젝트 루트)components/ui/ (shadcn/ui)store/hooks/query/any 사용 금지 — 반드시 unknown + 타입 가드 사용
// ❌ FORBIDDEN
function handleData(data: any) { return data.id }
// ✅ CORRECT
function handleData(data: User) { return data.id }
function processUnknown(data: unknown) {
if (isUser(data)) return data.id
}
lib/env.ts의 Zod 검증 값 사용 (process.env 직접 접근 금지)
// ❌ FORBIDDEN
const key = process.env.API_KEY
// ✅ CORRECT
import { env } from '@/lib/env'
const url = env.NEXT_PUBLIC_API_URL
cn() 유틸리티로 조건부 클래스명 처리isLoading, hasError, canSubmit)중요: 이 프로젝트는 하이브리드 SPA입니다!
- UI/페이지: Client Components (
'use client')- 인증(HttpOnly 쿠키): SSR 허용 (보안상 필수)
'use client' 디렉티브 필수output: 'standalone' (Node.js 서버 배포)app/api/[...path]/route.ts) — 백엔드 프록시 + 토큰 갱신용app/actions/auth-actions.ts) — HttpOnly 쿠키 관리용next/headers) — 인증 관련 함수에서만 사용'use client' 필수useEffect로 데이터 페칭 금지 — React Query 사용staleTime/gcTime 적절히 설정persist 미들웨어로 localStorage 지속app/
├── (auth)/ # 인증 라우트 그룹
│ ├── login/page.tsx
│ └── register/page.tsx
├── (admin)/ # 메인 앱 라우트 그룹 (보호됨)
│ ├── layout.tsx # Layout with Header, Sidebar
│ ├── dashboard/page.tsx
│ └── users/
│ ├── page.tsx
│ └── [id]/page.tsx
├── layout.tsx # Root layout (Providers)
└── page.tsx
components/
├── ui/ # shadcn/ui (수정 금지)
└── common/ # Header, Sidebar, Loading, ErrorBoundary
lib/
├── api-client.ts # Axios 인스턴스
├── auth/ # 인증 (auth-service, session-manager)
├── env.ts # 환경변수 (Zod 검증)
└── utils.ts # cn, format 등
hooks/ # React Query 훅, 커스텀 훅
store/ # Zustand stores
types/ # TypeScript 타입 정의
public/ # 정적 자산
tests/ & playwright/ # 테스트 설정
"use client" 디렉티브: 클라이언트 컴포넌트에만 사용