Next.js는 프로젝트 파일을 어떻게 구성할지에 대해 강제하지 않지만, 프로젝트를 체계적으로 관리할 수 있도록 다양한 기능을 제공합니다.
컴포넌트 계층 구조 (Component hierarchy)
특수 파일에 정의된 컴포넌트들은 다음과 같은 계층 구조로 렌더링됩니다:
layout.jstemplate.jserror.js(React 에러 바운더리)loading.js(React suspense 바운더리)not-found.js(React 에러 바운더리)page.js또는 중첩된layout.js
이 컴포넌트들은 중첩 라우트에서 재귀적으로 렌더링되며, 하위 세그먼트의 컴포넌트는 상위 세그먼트 컴포넌트 내부에 중첩됩니다.
파일 동반 배치(Colocation)
app 디렉토리에서 중첩 폴더는 라우트 구조를 정의합니다. 각 폴더는 URL 경로의 세그먼트에 매핑됩니다.
단, 폴더 구조만으로는 라우트가 공개되지 않으며, 해당 세그먼트에 page.js 또는 route.js 파일이 추가되어야만 외부에서 접근할 수 있습니다.
참고: 라우트가 공개되어도, 클라이언트에는 오직
page.js또는route.js가 반환하는 내용만 전달됩니다.
따라서, 프로젝트 파일을 app 디렉토리 내 라우트 세그먼트에 자유롭게 동반 배치해도 라우트로 노출되지 않습니다.
참고: 반드시
app내부에 파일을 동반 배치할 필요는 없으며, 원한다면 외부에 둘 수도 있습니다.
프라이빗 폴더 (Private folders)
폴더명 앞에 언더스코어(_)를 붙이면 프라이빗 폴더로 간주되어 라우팅 시스템에서 제외됩니다. 해당 폴더와 하위 폴더 전체가 라우팅에서 빠집니다.
프라이빗 폴더는 다음과 같은 경우에 유용합니다:
- UI 로직과 라우팅 로직 분리
- 내부 파일을 일관되게 관리
- 코드 에디터에서 파일 정렬 및 그룹화
- 향후 Next.js 파일 컨벤션과의 네이밍 충돌 방지
참고:
- 프라이빗 폴더를 사용하지 않아도, Next.js의 파일 컨벤션을 숙지하면 예기치 않은 네이밍 충돌을 예방할 수 있습니다.
- URL 세그먼트에 언더스코어를 사용하려면
%5F(언더스코어의 URL 인코딩)로 폴더명을 지정하세요.
라우트 그룹 (Route groups)
폴더명을 괄호로 감싸면(예: (folderName)) 라우트 그룹이 생성됩니다. 라우트 그룹은 URL 경로에 포함되지 않으며, 오직 프로젝트 구조상 그룹화 용도로만 사용됩니다.
라우트 그룹은 다음과 같은 경우에 유용합니다:
- 사이트 섹션, 목적, 팀별로 라우트 정리
- 동일 세그먼트 내 중첩 레이아웃 구성
- 특정 하위 라우트에만 레이아웃 적용
src 폴더
Next.js는 app을 포함한 애플리케이션 코드를 선택적으로 src 폴더 내에 둘 수 있습니다. 이렇게 하면 프로젝트 루트의 설정 파일과 애플리케이션 코드를 분리할 수 있습니다.
예시: 다양한 프로젝트 구조 전략
아래는 일반적으로 사용되는 프로젝트 구조 전략의 예시입니다. 팀에 맞는 전략을 선택해 일관성 있게 사용하는 것이 중요합니다.
참고: 예시에서 사용하는
components,lib폴더 등은 관례적 명칭일 뿐, Next.js에서 특별한 의미를 갖지 않습니다. 필요에 따라ui,utils,hooks,styles등 다양한 폴더명을 사용할 수 있습니다.
1. app 외부에 프로젝트 파일 배치
모든 애플리케이션 코드를 프로젝트 루트의 공유 폴더에 두고, app 디렉토리는 라우팅 용도로만 사용합니다.
2. app 내부 최상위 폴더에 프로젝트 파일 배치
공유 코드 폴더를 app 디렉토리의 최상위에 두고 관리합니다.
3. 기능/라우트별로 파일 분리
전역적으로 공유되는 코드는 app 루트에 두고, 특정 라우트에서만 사용하는 코드는 해당 세그먼트 폴더에 배치합니다.
4. URL 경로에 영향 없이 라우트 그룹으로 정리
괄호로 감싼 폴더를 사용해 관련 라우트를 그룹화하되, URL 경로에는 영향을 주지 않습니다. 예: (marketing), (shop) 등
5. 특정 라우트에만 레이아웃 적용
특정 라우트만 별도의 레이아웃을 사용하려면, 새로운 라우트 그룹을 만들고 해당 라우트들을 그룹 내로 이동시킵니다.
6. 특정 라우트에만 로딩 스켈레톤 적용
특정 라우트에만 loading.js를 적용하려면, 해당 라우트 그룹 내에 loading.tsx를 배치하세요.
7. 다중 루트 레이아웃 구성
여러 개의 루트 레이아웃이 필요하다면, 최상위 layout.js를 제거하고 각 라우트 그룹에 별도의 layout.js를 추가하세요. 각 루트 레이아웃에는 <html>과 <body> 태그가 필요합니다.
본 문서는 Next.js 공식 문서 - Project Structure에서 번역되었습니다.
