Next.js 모범 사례
Next.js 코드를 작성하거나 검토할 때 다음 규칙을 적용하세요.
파일 규칙
자세한 내용은 file-conventions.md를 참조하세요:
- 프로젝트 구조 및 특수 파일
- 라우트 세그먼트 (동적, 포괄적, 그룹)
- 병렬 및 인터셉팅 라우트
- v16에서 미들웨어 이름 변경 (middleware → proxy)
RSC 경계
잘못된 React 서버 컴포넌트 패턴을 감지합니다.
자세한 내용은 rsc-boundaries.md를 참조하세요:
- 비동기 클라이언트 컴포넌트 감지 (잘못됨)
- 직렬화 불가능한 props 감지
- 서버 액션 예외 처리
비동기 패턴
Next.js 15+ 비동기 API 변경 사항.
자세한 내용은 async-patterns.md를 참조하세요:
- 비동기
params및searchParams - 비동기
cookies()및headers() - 마이그레이션 codemod
런타임 선택
자세한 내용은 runtime-selection.md를 참조하세요:
- 기본적으로 Node.js 런타임 사용
- Edge 런타임이 적합한 경우
지시문
자세한 내용은 directives.md를 참조하세요:
'use client','use server'(React)'use cache'(Next.js)
함수
자세한 내용은 functions.md를 참조하세요:
- 탐색 훅:
useRouter,usePathname,useSearchParams,useParams - 서버 함수:
cookies,headers,draftMode,after - 생성 함수:
generateStaticParams,generateMetadata
에러 처리
자세한 내용은 error-handling.md를 참조하세요:
error.tsx,global-error.tsx,not-found.tsxredirect,permanentRedirect,notFoundforbidden,unauthorized(인증 에러)- catch 블록에서
unstable_rethrow
데이터 패턴
자세한 내용은 data-patterns.md를 참조하세요:
- 서버 컴포넌트 vs 서버 액션 vs 라우트 핸들러
- 데이터 워터폴 방지 (
Promise.all, Suspense, preload) - 클라이언트 컴포넌트 데이터 가져오기
라우트 핸들러
자세한 내용은 route-handlers.md를 참조하세요:
route.ts기본 사항page.tsx와 GET 핸들러 충돌- 환경 동작 (React DOM 없음)
- 서버 액션 대비 사용 시기
메타데이터 및 OG 이미지
자세한 내용은 metadata.md를 참조하세요:
- 정적 및 동적 메타데이터
generateMetadata함수next/og를 사용한 OG 이미지 생성- 파일 기반 메타데이터 규칙
이미지 최적화
자세한 내용은 image.md를 참조하세요:
- 항상
<img>대신next/image사용 - 원격 이미지 구성
- 반응형
sizes속성 - 블러 플레이스홀더
- LCP를 위한 우선 로딩
폰트 최적화
자세한 내용은 font.md를 참조하세요:
next/font설정- Google Fonts, 로컬 폰트
- Tailwind CSS 통합
- 서브셋 사전 로드
번들링
자세한 내용은 bundling.md를 참조하세요:
- 서버 비호환 패키지
- CSS 임포트 (link 태그 아님)
- 폴리필 (이미 포함됨)
- ESM/CommonJS 문제
- 번들 분석
스크립트
자세한 내용은 scripts.md를 참조하세요:
next/scriptvs 네이티브 script 태그- 인라인 스크립트에는
id필요 - 로딩 전략
@next/third-parties를 사용한 Google Analytics
하이드레이션 에러
자세한 내용은 hydration-error.md를 참조하세요:
- 일반적인 원인 (브라우저 API, 날짜, 잘못된 HTML)
- 에러 오버레이로 디버깅
- 각 원인에 대한 수정 방법
Suspense 경계
자세한 내용은 suspense-boundaries.md를 참조하세요:
useSearchParams및usePathname을 사용한 CSR 전환- Suspense 경계가 필요한 훅
병렬 및 인터셉팅 라우트
자세한 내용은 parallel-routes.md를 참조하세요:
@slot및(.)인터셉터를 사용한 모달 패턴- 폴백을 위한
default.tsx router.back()을 사용하여 모달을 올바르게 닫기
자체 호스팅
자세한 내용은 self-hosting.md를 참조하세요:
- Docker를 위한
output: 'standalone' - 다중 인스턴스 ISR을 위한 캐시 핸들러
- 작동하는 것과 추가 설정이 필요한 것
디버그 팁
자세한 내용은 debug-tricks.md를 참조하세요:
- AI 지원 디버깅을 위한 MCP 엔드포인트
--debug-build-paths로 특정 라우트 재빌드