Next.js 프로젝트 구조 가이드

Next.js로 프로젝트를 시작할 때 가장 먼저 고민하게 되는 것이 바로 폴더와 파일의 구조입니다.
이 글에서는 Next.js의 폴더 및 파일 컨벤션, 그리고 실제로 유지보수와 확장에 유리한 구조 설계 방법을 예시와 함께 소개합니다.

1. 프로젝트 구조와 조직 방법

Next.js 프로젝트의 폴더와 파일 규칙은 애플리케이션의 구조와 컨벤션에 대한 명확한 가이드라인을 제공합니다.
최상위 폴더들은 코드를 조직하고 정적 자산을 관리하는 역할을 하며, 대표적으로 app, pages, public, src 폴더가 자주 사용됩니다.
또한, 최상위 파일들은 애플리케이션의 설정, 의존성 관리, 미들웨어, 환경변수 등을 정의하는 데 활용됩니다.

1.1. 프로젝트 구조와 폴더 및 파일 컨벤션

Next.js 프로젝트 구조의 기본 원칙

Next.js에서는 상위 폴더와 파일의 역할과 위치가 명확하게 정해져 있어, 프로젝트를 체계적으로 조직할 수 있습니다.
최상위 폴더에는 엔트리 포인트, 공개 자산, 언어 설정 등 기본 파일들이 위치하며, 이 구조가 프로젝트 전반에 영향을 줍니다.
라우팅 관련 파일과 폴더는 app 디렉터리 내에 배치되며, 폴더 구조와 파일 이름에 따라 자동으로 라우트가 생성됩니다.

라우팅 및 폴더 구성 방법

네임스페이스와 라우트 그룹(Route Groups), 프라이빗 폴더(Private Folders)를 활용해 라우트를 구분할 수 있으며, 이 구조는 URL 경로에 영향을 주지 않습니다.
src 폴더를 별도로 사용하는 경우, 프로젝트 파일을 기능별 또는 라우트별로 분리하여 관리가 용이해집니다.
프로젝트의 확장성과 유지보수를 위해 컴포넌트, 페이지, 레이아웃 등을 유기적으로 배치하는 것이 권장됩니다.

고급 구성 기법

프로젝트 외부에 기능별 또는 라우트별로 폴더를 분리하거나, 특정 세그먼트를 로드하는 스켈레톤 기법, 여러 루트 레이아웃 등을 활용할 수 있습니다.
앱 아이콘, 오픈 그래프, 소셜 미디어 이미지를 포함한 메타데이터 파일의 표준 위치와 명명 규칙이 정해져 있습니다.
프로젝트 구조 설계 시 SEO, 코드 조직화, 유지보수 용이성을 반드시 고려해야 하며, 이에 따른 다양한 예시와 권장 방식이 존재합니다.

1.2. 최상위 폴더의 역할과 구성

최상위 폴더는 애플리케이션의 코드와 정적 자산을 조직하는 데 사용됩니다.
이러한 폴더 구조는 프로젝트의 유지보수와 확장에 큰 도움을 주며, 폴더 명명 규칙은 일관성을 유지하고 역할에 따라 구분하는 것이 좋습니다.

1.3. 애플리케이션 구조에서 상위 수준 파일의 역할

최상위 파일들은 애플리케이션의 설정, 의존성 관리, 미들웨어 실행, 모니터링 도구 통합, 환경 변수 정의 등에 사용됩니다.
이러한 파일들은 애플리케이션의 핵심 구성과 운영에 필수적이며, 상위 수준 폴더에 위치하는 구성 파일들은 프로젝트의 전반적인 기반을 형성합니다.

2. 프로젝트 구조와 폴더 구성

Next.js는 프로젝트 파일 구성에 관한 엄격한 규칙이 없지만, 여러 기능을 통해 다양한 구성 방식을 지원합니다.
컴포넌트들은 특별한 파일(layout.js, template.js, error.js, loading.js, not-found.js, page.js)에 정의되어 계층적으로 렌더링되며, 폴더가 중첩될수록 URL 경로와 매핑됩니다.

비공개 폴더는 폴더 이름 앞에 언더스코어(_)를 붙여 만들며, 라우팅 시스템에서 제외됩니다.
폴더를 소괄호(())로 감싸면 라우트 그룹이 되어 URL에 노출되지 않는 조직용 폴더로 사용할 수 있습니다.

폴더 활용과 관리

프로젝트 내 폴더는 내재된 라우트 구조를 나타내며, 별도의 라우팅 규칙 없이 폴더 기반으로 배치됩니다.
내부 폴더와 파일로 라우트를 조직하며, 필요한 경우 폴더별로 레이아웃 또는 UI 논리를 구분할 수 있습니다.
app 디렉토리 내 파일들은 안전하게 위치하며, 필요 시 프로젝트 외부에 둔 폴더를 활용할 수도 있습니다.
Next.js는 src 폴더 안에 애플리케이션 코드를 배치하는 것도 지원하여 구성과 분리를 용이하게 합니다.

기타 중요한 규칙

라우트 폴더는 page.js 또는 route.js 파일이 있어야만 공개적 라우트가 됩니다.
비공개 폴더는 라우팅 대상에서 제외하는 대신, 내부 UI와 로직 구분에 유용합니다.
폴더 그룹은 일반 폴더 이름 대신 소괄호로 감싸며, URL에 노출되지 않고 조직적 목적으로 사용됩니다.

3. 프로젝트 구조 선택 전략

프로젝트와 팀에 적합한 구조 전략을 선택하고, 전체 프로젝트에서 일관되게 적용하는 것이 중요합니다.
여러 폴더 이름(예: components, lib 등)은 프레임워크에 특수한 의미가 없으며, 필요에 따라 ui, utils, hooks, styles 등으로 자유롭게 변경할 수 있습니다.

애플리케이션 코드 저장 위치 전략

모든 애플리케이션 코드를 루트의 공유 폴더에 저장하고, app 디렉토리는 오로지 라우팅 용도로만 사용하는 전략이 있습니다.
또는, 애플리케이션 코드를 app 디렉토리 내의 상위 폴더(예: ui, utils) 안에 저장하는 방법도 있습니다.

기능 또는 라우트별 파일 분할 전략

전역 공유 코드는 루트 app 디렉토리에 보관하고, 특정 기능이나 라우트별 코드는 해당 라우트 세그먼트에 분리하는 전략이 있습니다.

라우트 구성 및 URL 경로 비반영 방법

URL에는 영향을 주지 않으면서 라우트를 조직하려면, 관련 라우트를 그룹으로 묶는 방법이 사용됩니다.
그룹으로 묶인 폴더 이름(예: marketing, shop)은 URL에 표시되지 않으며, 이 폴더에 layout.js를 추가해 각 그룹별 레이아웃을 별도로 구성할 수 있습니다.

4. 특정 경로를 레이아웃에 선택적으로 적용하는 방법

동일한 레이아웃을 적용할 특정 라우트는 새로운 라우트 그룹을 만들어서 그룹 내에 배치합니다.
예를 들어, (shop) 그룹에는 관련 라우트만 넣고, 그룹 외부의 라우트는 해당 레이아웃을 상속받지 않게 할 수 있습니다.

특정 라우트에만 로딩 스켈레톤을 적용하려면, 해당 라우트 그룹에 loading.tsx 파일을 생성해 위치시키면 됩니다.
여러 개의 루트 레이아웃을 만들려면, 최상위 layout.js 파일을 제거하고 각 그룹 내부에 layout.js 파일을 넣으면 됩니다.
이 방법은 UI 또는 경험이 완전히 다른 섹션에 대해 구분하여 애플리케이션을 구조화하는 데 유용합니다.

각각의 루트 레이아웃에는 반드시 <html>과 <body> 태그가 포함되어야 하며, 예시로 (marketing)과 (shop) 그룹은 별도의 루트 레이아웃을 사용할 수 있습니다.

이 글을 참고하여 여러분의 Next.js 프로젝트 구조를 더욱 체계적이고 확장성 있게 설계해보시기 바랍니다!