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

폴더별 역할과 배치를 설명하며, 자산을 어디에 배치할지에 대한 설명을 드리겠습니다.

 

1. Next.js 14 권장 폴더 구조

Next.js 14 프로젝트의 기본적인 폴더 구조는 아래와 같습니다. 이 구조를 통해 코드를 모듈화하고, 확장 가능하며, 유지보수하기 쉽게 설계할 수 있습니다.

/app
  └── /api
/components
/lib
/utils
/assets
/constants
/public
/styles

public 폴더는 정적 파일 제공을 위한 표준 폴더이며, 이곳에 파일을 배치하면 프로젝트 루트 URL에서 바로 접근할 수 있습니다. 이외의 경우에는 프로젝트 모듈 내에서만 활용되는 자산을 관리하기 위해 /app이나 /src 내부에 독립적으로 assets 폴더를 둘 수도 있습니다.

(Medium, Reddit을 확인하다보면 assets과 public 폴더를 같은 최상위에 위치시켜서 사용하는 사람들이 많았습니다.)

개인적으로 assets폴더는 public폴더 내부에 넣어 사용하고 있습니다.

 

2. 폴더별 역할과 배치

• /app

  • 프로젝트의 주요 폴더입니다. Next.js 14에서 App Router 기능을 사용하는 경우, 이 폴더 안에서 페이지와 API 라우트를 정의합니다.

  • api: API 라우트를 정의하는 디렉토리로, API 핸들러 파일들이 위치합니다.

• /components

  • 재사용 가능한 UI 컴포넌트를 배치하는 폴더입니다. 버튼, 모달, 폼과 같은 UI 요소들을 여기에 배치하여 프로젝트 전반에 걸쳐 활용할 수 있습니다.

• /lib

  • 외부 라이브러리 설정 파일이나 설정 데이터를 배치하는 폴더입니다. 예를 들어 데이터베이스 연결 설정, 인증 설정 등을 여기서 관리합니다.

• /utils

  • 프로젝트 전반에 걸쳐 자주 사용되는 유틸리티 함수들을 배치합니다. 날짜 형식 변환, 문자열 조작, 데이터 포맷팅 함수 등이 포함됩니다.

• /assets

  • 특정 모듈에서만 사용되는 자산을 저장하는 폴더입니다. 예를 들어 /app이나 /src 내부에 assets 폴더를 두어, 해당 모듈에서만 사용하는 이미지나 아이콘 등을 관리할 수 있습니다.

• /constants

  • 상수값을 정의하는 폴더입니다. API 엔드포인트, 기본 설정값 등 프로젝트에서 공유하고 사용할 설정값들을 배치하여 관리합니다.

• /public

  • 프로젝트의 정적 파일을 저장하는 Next.js 표준 폴더입니다. 이미지, 폰트, 아이콘 등 공용 정적 자산은 이곳에 assets 폴더를 만들어 배치하는 것이 일반적입니다.

  • 예를 들어, /public/assets/images/logo.png 파일은 브라우저에서 /assets/images/logo.png로 접근할 수 있습니다.

• /styles

  • 프로젝트 전반의 스타일링 파일을 배치합니다. CSS 또는 SASS 파일들을 저장하며, 전역 스타일 파일인 global.css도 여기에 포함됩니다.

 

3. 폴더 구조의 중요성

Next.js의 폴더 구조를 적절히 설계하면 다음과 같은 이점을 얻을 수 있습니다:

• 재사용성: 공통 컴포넌트 및 함수들을 쉽게 재사용할 수 있어 개발 효율성이 증가합니다.

• 가독성: 코드가 정돈되고 역할별로 분리되어 있어 가독성이 향상됩니다.

• 유지보수성: 폴더별 역할이 명확하여 수정이 필요한 부분을 빠르게 찾고 업데이트할 수 있습니다.