프로젝트 구성 및 파일 Colocation

라우팅 폴더 및 파일 규칙을 제외하고, Next.js는 프로젝트 파일을 구성하고, 배치하는 방법에 대해 의견을 제시하지 않습니다.

이 페이지에서는 프로젝트를 구성하는 데 사용할 수 있는 기본 동작과 기능을 공유합니다.

1. 기본적으로 안전한 코로케이션

app 디렉토리에서 중첩된 폴더 계층 구조는 경로 구조를 정의합니다.

각 폴더는 URL 경로의 해당 세그먼트에 매핑되는 경로 세그먼트를 나타냅니다.

그러나, 경로 구조가 폴더를 통해 정의되더라도, page.js 또는 route.js 파일이 경로 세그먼트에 추가될 때까지는, 경로에 공개적으로 액세스할 수 없습니다.

라우팅-용어

또한 경로가 공개적으로 액세스 가능하도록 설정된 경우에도, page.js 또는 route.js에서 반환한 콘텐츠만 클라이언트로 전송됩니다.

라우팅-용어

즉, 프로젝트 파일을 app 디렉터리의 경로 세그먼트 내에 안전하게 배치하여, 실수로 라우팅할 수 없게 만들 수 있습니다.

라우팅-용어

알아두면 유용합니다:

이 디렉토리는 page의 모든 파일이 경로로 간주되는, page 디렉토리와는 다릅니다.

프로젝트 파일을 app에 배치할 수는 있지만 반드시 그럴 필요는 없습니다.

원하는 경우 app 디렉터리 외부에 보관할 수 있습니다.

2. 프로젝트 구성 기능

Next.js는 프로젝트를 구성하는 데 도움이 되는 몇 가지 기능을 제공합니다.

2.1 Private Folders (비공개 폴더)

비공개 폴더는 폴더 앞에 밑줄을 붙여 만들 수 있습니다: _폴더 이름

이는 해당 폴더가 비공개 구현 세부정보이며, 라우팅 시스템에서 고려하지 않아야 함을 나타내므로, 해당 폴더 및 모든 하위 폴더를 라우팅에서 제외합니다.

Private Folders

app 디렉토리에 있는 파일은 기본적으로 안전하게 배치할 수 있으므로, 코로케이션에는 비공개 폴더가 필요하지 않습니다. 하지만 다음과 같은 경우 유용할 수 있습니다:

UI 로직과 라우팅 로직을 분리하는 경우.
프로젝트와 Next.js 에코시스템 전반에서 내부 파일을 일관되게 구성.
코드 편집기에서 파일 정렬 및 그룹화.
향후 Next.js 파일 규칙과의 잠재적인 이름 지정 충돌 방지.

알아두면 유용한 정보

프레임워크 규칙은 아니지만 동일한 밑줄 패턴을 사용하여, 비공개 폴더 외부의 파일을 “비공개”로 표시하는 것도 고려해 볼 수 있습니다.

폴더 이름 앞에 %5F(밑줄의 URL 인코딩 형식)를 붙여서 밑줄로 시작하는 URL 세그먼트를 만들 수 있습니다: %5FfolderName.

비공개 폴더를 사용하지 않는 경우, 예기치 않은 이름 지정 충돌을 방지하기 위해 Next.js 특수 파일 규칙을 알아두면 도움이 될 것입니다.

2.2 Route Groups (라우트 그룹)

폴더를 괄호로 묶어 경로 그룹을 만들 수 있습니다: (폴더이름)

이는 폴더가 관리용이며, 경로의 URL 경로에 포함되어서는 안 되는 폴더임을 나타냅니다.

Route Groups

경로 그룹은 다음과 같은 경우에 유용합니다:

경로를 그룹으로 구성하기 e.g. 사이트 섹션, 의도 또는 팀별
동일한 경로 세그먼트 수준에서 중첩 레이아웃 사용:
- 여러 루트 레이아웃을 포함하여 동일한 세그먼트에 여러 개의 중첩 레이아웃 만들기
- 공통 세그먼트의 라우트 하위 집합에 레이아웃 추가하기

2.3 src 디렉토리

Next.js는 애플리케이션 코드(app 포함)를 선택적 src 디렉토리에 저장할 수 있도록 지원합니다. 이렇게 하면 대부분 프로젝트의 루트에 있는 프로젝트 구성 파일과 애플리케이션 코드를 분리할 수 있습니다.

Route Groups

2.4 모듈 경로 별칭

Next.js는 모듈 경로 별칭을 지원하므로, 깊게 중첩된 프로젝트 파일에서 imports를 쉽게 읽고 유지 관리할 수 있습니다.

app/dashboard/settings/analytics/page.js

1// before
2import { Button } from '../../../components/button'
3
4// after
5import { Button } from '@/components/button'

3. 프로젝트 정리 전략

Next.js 프로젝트에서 파일과 폴더를 정리하는 데 있어 “옳고 그른” 방법은 없습니다.

다음 섹션에서는 일반적인 전략에 대한 매우 높은 수준의 개요를 나열합니다. 가장 간단한 요점은 여러분과 팀에 적합한 전략을 선택하고 프로젝트 전체에서 일관성을 유지하는 것입니다.

알아두면 좋습니다:

아래 예제에서는, components와 lib 폴더를 일반화된 플레이스홀더로 사용하고 있으며,

그 이름에는 특별한 프레임워크의 의미가 없으며 프로젝트에서 ui, utils, hook, style 등과 같은 다른 폴더를 사용할 수도 있습니다.

3.1 앱 외부에 프로젝트 파일 저장

이 전략은 모든 애플리케이션 코드를 프로젝트 루트의 공유 폴더에 저장하고, app 디렉터리는 순전히 라우팅 목적으로만 유지합니다.

Route Groups

3.2 앱 내 최상위 폴더에 프로젝트 파일 저장

이 전략은 모든 애플리케이션 코드를 app 디렉터리의 루트에 있는 공유 폴더에 저장합니다.

Route Groups

3.3 기능 또는 경로별로 프로젝트 파일 분할

이 전략은 전역적으로 공유되는 애플리케이션 코드를 루트 app 디렉터리에 저장하고, 이를 사용하는 경로 세그먼트에 보다 구체적인 애플리케이션 코드를 분할하는 전략입니다.

Route Groups

07-Route Groups 09-Dynamic Routes