우선순위: P0 (매우 중요)
구현 가이드라인
라우팅 아키텍처
- 구조:
app/디렉터리를 사용하세요. **app/dashboard/layout.tsx**에서 **{children}**을 반환하여 경로를 정의합니다. 공유 UI는 자동으로app/layout.tsx내에 중첩됩니다.loading.tsx,error.tsx, **not-found.tsx**로 상태를 처리합니다. - 세그먼트: Route Groups (대괄호
(auth))를 사용하여 URL 경로에서 제외되는 방식으로 기능을 구성하세요. Dynamic Routes (대괄호[slug])를 사용하고 **generateStaticParams**를 통해 정적 경로를 정의합니다. - 고급 기능: Parallel Routes (
@modal)는 슬롯을 부모 레이아웃에 추가하고default.tsx폴백을 제공하여 사용합니다. 대시보드와 같은 고급 레이아웃에는 Intercepting Routes ((.)route)를 사용합니다.
데이터 및 함수
-
Next.js 15+ 비동기:
params: Promise,searchParams,cookies()및 **headers()**는 항상await해야 합니다. -
보안: **
middleware.ts**를 사용하여 에지-사이드 인증 및 리디렉션을 처리하고, 모든 **Route Handler (route.ts)**에 적절한 인증 검사를 적용합니다. -
RSC: 기본적으로 **React Server Components (RSC)**를 사용합니다. 인터랙티브한 부분(훅/이벤트)에서만 **
'use client'**를 리프 노드에 사용합니다. -
에러 바운더리: **
app/dashboard/loading.tsx**를 생성하여 경로를 자동으로 Suspense 경계로 감쌉니다. **error.tsx**에서는 **'use client'**를 사용하고reset: () => void함수를 제공합니다.const theme = cookieStore.get('theme');
## 파일 컨벤션
- **page.tsx**: 경로의 UI를 정의합니다.
- **layout.tsx**: 자식 요소를 감싸는 공유 UI로, 네비게이션 간에 유지됩니다.
- **loading.tsx**: 로딩 상태를 위한 Suspense 경계입니다.
- **error.tsx**: 에러 경계 (클라이언트 컴포넌트여야 함).
- **route.ts**: 서버 측 API 엔드포인트를 정의합니다.
## 구조 패턴
- **Route Groups**: 괄호 `(auth)`를 사용하여 URL 경로에 영향을 주지 않고 구조를 구성합니다.
- **Private Folders**: 밑줄 `_lib`을 사용하여 라우팅에서 제외합니다.
- **Dynamic Routes**: 대괄호 `[slug]` 또는 `[...slug]` (캐치-올)을 사용합니다.
## 모범 사례
- **RSC 경계**: 클라이언트 컴포넌트에 전달되는 props는 직렬화 가능해야 합니다. [RSC 경계 및 직렬화](../architecture/references/RSC_BOUNDARIES.md)를 참조하세요.
- **Parallel Routes (`@folder`)**: 동일한 레이아웃에서 여러 페이지를 렌더링합니다. 폴백으로 `default.tsx`를 사용합니다.
- **Intercepting Routes (`(..)folder`)**: 현재 레이아웃 컨텍스트 내에서 경로를 로드합니다.
- **Colocation**: 컴포넌트 파일, 스타일, 테스트를 경로 폴더 내에 함께 배치합니다.
- **Layouts**: 루트 레이아웃 (`app/layout.tsx`)에서 `<html>` 및 `<body>` 태그를 사용합니다.
- [**셀프-호스팅 표준**](references/SELF_HOSTING.md)
## 안티패턴
- **await하지 않은 비동기 API 금지**: `params`, `cookies()`, `headers()`는 Next.js 15+에서 Promise입니다. 항상 await하세요.
- **트리 루트에서 `'use client'` 금지**: 리프 노드에만 배치하고, 레이아웃과 페이지는 서버 컴포넌트로 유지합니다.
- **중첩 레이아웃에서 `<html>`/`<body>` 금지**: `app/layout.tsx` (루트 레이아웃)에서만 포함해야 합니다.
- **`error.tsx` 누락 금지**: 모든 경로 세그먼트에는 클라이언트 컴포넌트 에러 바운더리가 필요합니다.