프로젝트 구조 이해하기
Next.js 16 프로젝트를 성공적으로 생성하고 실행하셨으니, 이제 우리가 앞으로 작업하게 될 프로젝트의 내부 구조를 좀 더 깊이 있게 이해하는 시간을 가져보겠습니다. 프로젝트의 각 디렉터리와 파일이 어떤 역할을 하는지 알면, 코드를 작성하고 관리하는 데 훨씬 수월해집니다.
앞서 create-next-app으로 프로젝트를 생성할 때 src/ 디렉터리 사용을 선택했으므로, 그에 맞춰 src 폴더를 기준으로 설명을 진행하겠습니다.
주요 디렉터리 및 파일
Next.js 프로젝트의 핵심은 src 디렉터리 안에 있는 app 디렉터리입니다. 이 외에도 몇 가지 중요한 최상위 디렉터리와 파일들이 있습니다.
src/ 디렉터리
프로젝트의 소스 코드가 위치하는 곳입니다. create-next-app에서 src/ 디렉터리 사용을 선택했다면, 모든 애플리케이션 코드는 이 안에 작성됩니다.
src/app/ 디렉터리 (App Router의 핵심)
이 디렉터리는 Next.js 16의 App Router가 작동하는 방식의 핵심입니다. app 디렉터리 내의 파일 및 폴더 구조가 애플리케이션의 라우팅을 정의합니다.
-
src/app/page.tsx(또는.js,.jsx)- 애플리케이션의 루트 페이지를 나타냅니다. 즉,
http://localhost:3000/로 접속했을 때 가장 먼저 보이는 페이지입니다. - 각 라우트 세그먼트(폴더) 안에
page.tsx파일이 있으면 해당 라우트의 UI가 렌더링됩니다. - 이 파일은 기본적으로 서버 컴포넌트(Server Component)로 동작합니다.
- 애플리케이션의 루트 페이지를 나타냅니다. 즉,
-
src/app/layout.tsx(또는.js,.jsx)- 애플리케이션의 공통 레이아웃을 정의하는 파일입니다.
<html>및<body>태그와 같이 모든 페이지에 걸쳐 공유되는 UI를 여기에 정의합니다.- 최상위
layout.tsx는 반드시 존재해야 하며, 그 안에<html lang="ko">와 같은 HTML 태그를 포함해야 합니다. layout.tsx파일은 기본적으로 서버 컴포넌트로 동작합니다.
-
src/app/global.css- 애플리케이션 전체에 적용되는 전역 스타일을 정의하는 CSS 파일입니다.
layout.tsx파일에서 이 CSS 파일을 임포트하여 사용합니다.
-
라우트 세그먼트 폴더 (예:
src/app/dashboard/page.tsx)app디렉터리 안에 새로운 폴더를 생성하면, 해당 폴더 이름이 URL 경로의 세그먼트가 됩니다.- 예를 들어,
src/app/dashboard/page.tsx는/dashboard경로에 매핑됩니다. - 폴더 안에
page.tsx파일이 없으면 해당 경로는 유효한 페이지가 아닙니다.
-
loading.tsx(선택 사항)- 특정 라우트 세그먼트의 콘텐츠가 로딩되는 동안 보여줄 UI를 정의합니다.
- Next.js의 Suspense 기능과 함께 작동하여 사용자 경험을 향상시킵니다.
-
error.tsx(선택 사항)- 특정 라우트 세그먼트에서 에러가 발생했을 때 보여줄 UI를 정의합니다.
- React Error Boundary와 유사하게 작동하여 애플리케이션의 안정성을 높입니다.
-
not-found.tsx(선택 사항)- 해당 라우트에서 콘텐츠를 찾을 수 없을 때 보여줄 UI를 정의합니다. (404 페이지)
public/ 디렉터리
이미지, 폰트, favicon.ico 등 웹 서버에서 직접 제공되어야 하는 정적 파일들을 저장하는 곳입니다. 이 디렉터리 안의 파일들은 애플리케이션의 루트 경로에서 바로 접근할 수 있습니다. 예를 들어, public/logo.png 파일은 /logo.png 경로로 접근할 수 있습니다.
node_modules/ 디렉터리
npm install 또는 yarn add 명령어를 통해 설치된 모든 Node.js 패키지(라이브러리)들이 저장되는 곳입니다. 이 폴더는 용량이 매우 크므로, Git과 같은 버전 관리 시스템에는 포함시키지 않는 것이 일반적입니다. (.gitignore 파일에 이미 설정되어 있습니다.)
.next/ 디렉터리
Next.js가 애플리케이션을 빌드(Build)할 때 생성되는 빌드 결과물, 캐시, 최적화된 파일 등이 저장되는 곳입니다. 이 디렉터리의 내용은 Next.js에 의해 관리되므로, 개발자가 직접 수정할 필요는 없습니다.
주요 설정 파일
프로젝트의 최상위 디렉터리에는 Next.js 애플리케이션의 동작을 제어하는 몇 가지 중요한 설정 파일들이 있습니다.
-
package.json- 프로젝트의 이름, 버전, 설명 등 메타데이터를 정의합니다.
dependencies에는 프로젝트 실행에 필요한 라이브러리 목록이,devDependencies에는 개발 시에만 필요한 라이브러리 목록이 정의됩니다.scripts섹션에는npm run dev,npm run build,npm run start와 같이 자주 사용하는 명령어가 정의되어 있습니다.
-
next.config.js- Next.js 애플리케이션의 커스텀 설정을 정의하는 파일입니다.
- 이미지 최적화, 환경 변수 설정, 웹팩(Webpack) 설정 변경 등 Next.js의 기본 동작을 변경하거나 확장할 때 사용합니다.
-
tsconfig.json(TypeScript 사용 시)- TypeScript 프로젝트에서 TypeScript 컴파일러의 설정을 정의하는 파일입니다.
- 어떤 버전의 JavaScript로 컴파일할지, 어떤 모듈 시스템을 사용할지 등을 설정합니다.
-
.eslintrc.json(ESLint 사용 시)- ESLint의 코드 스타일 및 정적 분석 규칙을 정의하는 파일입니다.
- 코드의 일관성을 유지하고 잠재적인 오류를 미리 발견하는 데 도움을 줍니다.
-
.gitignore- Git 버전 관리 시스템에서 추적하지 않을 파일이나 디렉터리를 지정하는 파일입니다.
node_modules/,.next/와 같이 불필요하거나 용량이 큰 파일/폴더는 여기에 포함되어 있습니다.
아래 다이어그램은 프로젝트 구조를 볼 때 각 파일의 역할과 수정·추적 여부를 함께 판단할 수 있도록 정리한 것입니다.
App Router의 라우팅 기본 원리
아래 다이어그램은 이 절의 핵심 흐름을 역할과 상태 전환 중심으로 정리한 것입니다.
App Router는 파일 시스템 기반 라우팅을 사용하지만, Pages Router와는 다르게 page.tsx 파일이 있는 폴더가 라우트 세그먼트가 됩니다.
- 루트 라우트:
src/app/page.tsx - 중첩 라우트:
src/app/dashboard/page.tsx->/dashboard - 동적 라우트:
src/app/products/[id]/page.tsx->/products/123(여기서[id]는 동적인 값)
이러한 구조를 통해 Next.js는 복잡한 라우팅 구조를 직관적으로 관리할 수 있게 하며, 각 라우트 세그먼트별로 독립적인 레이아웃, 로딩 UI, 에러 UI 등을 정의할 수 있는 강력한 기능을 제공합니다.
아래 다이어그램은 프로젝트 구조를 실제 수정 지점과 자동 생성물 기준으로 다시 묶어 보여줍니다.
다음 다이어그램은 Next.js 프로젝트 폴더를 라우팅, 재사용, 서버 로직, 정적 자산 책임으로 나누어 읽는 지도입니다.
아래 다이어그램은 이 섹션의 핵심 판단 기준과 적용 흐름을 한 번에 점검할 수 있도록 정리한 것입니다.