프로젝트 구조

Next.js 16 프로젝트 생성과 실행을 확인했으니, 이제 프로젝트 내부 구조를 살펴봅니다.

각 디렉터리와 파일의 역할을 알면 라우트, 컴포넌트, 설정 파일의 책임을 구분하기 쉽습니다.

앞서 create-next-app으로 프로젝트를 생성할 때 src/ 디렉터리 사용을 선택했으므로, 그에 맞춰 src 폴더를 기준으로 설명을 진행하겠습니다.

---

주요 디렉터리 및 파일

Next.js 프로젝트의 핵심은 src 디렉터리 안에 있는 app 디렉터리입니다.

이 외에도 몇 가지 중요한 최상위 디렉터리와 파일들이 있습니다.

src/ 디렉터리

프로젝트의 소스 코드가 위치하는 곳입니다.

이 교재는 src/ 아래에 애플리케이션 소스를 모읍니다. src/는 선택적 구성이고, public/과 package.json, next.config.ts 같은 설정 파일은 프로젝트 루트에 둡니다.

이후의 예시는 프로젝트 루트에 별도 app/이 없는 상태를 전제로 합니다. 루트의 app/도 만들어 놓으면 src/app/은 무시됩니다. 같은 page.tsx를 두 위치에 복사하기보다 실제 라우트 트리를 하나로 정하고 수정 위치를 확인합니다. 공식 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를 여기에 정의합니다.
  • 이 교재의 단일 라우트 트리에서는 src/app/layout.tsx가 Root Layout이며 <html lang="ko">와 <body>를 포함합니다. 라우트 그룹 등으로 여러 루트 트리를 구성할 때는 각 트리의 최상위 layout.tsx가 이 역할을 맡을 수 있습니다.
  • layout.tsx 파일은 기본적으로 서버 컴포넌트로 동작합니다.
• src/app/globals.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 개발 서버와 빌드가 생성하는 결과물과 캐시가 저장되는 곳입니다.

이 디렉터리의 내용은 Next.js에 의해 관리되므로, 개발자가 직접 수정할 필요는 없습니다.

---

주요 설정 파일

프로젝트의 최상위 디렉터리에는 Next.js 애플리케이션의 동작을 제어하는 몇 가지 중요한 설정 파일들이 있습니다.

• package.json
  • 프로젝트의 이름, 버전, 설명 등 메타데이터를 정의합니다.
  • dependencies에는 프로젝트 실행에 필요한 라이브러리 목록이, devDependencies에는 개발 시에만 필요한 라이브러리 목록이 정의됩니다.
  • scripts 섹션에는 npm run dev, npm run build, npm run start와 같이 자주 사용하는 명령어가 정의되어 있습니다.
• next.config.ts
  • Next.js 애플리케이션의 커스텀 설정을 정의하는 파일입니다.
  • 이미지 최적화와 번들러 설정 등 Next.js의 기본 동작을 조정합니다. Next.js 16은 Turbopack이 기본이며, webpack 설정은 Webpack을 선택한 실행에 적용됩니다.
• tsconfig.json (TypeScript 사용 시)
  • TypeScript 프로젝트에서 TypeScript 컴파일러의 설정을 정의하는 파일입니다.
  • 어떤 버전의 JavaScript로 컴파일할지, 어떤 모듈 시스템을 사용할지 등을 설정합니다.
• eslint.config.mjs (ESLint 사용 시)
  • ESLint의 코드 스타일 및 정적 분석 규칙을 정의하는 파일입니다.
  • 코드의 일관성을 유지하고 잠재적인 오류를 미리 발견하는 데 도움을 줍니다.
• .gitignore
  • Git 버전 관리 시스템에서 추적하지 않을 파일이나 디렉터리를 지정하는 파일입니다.
  • node_modules/, .next/와 같이 불필요하거나 용량이 큰 파일/폴더는 여기에 포함되어 있습니다.

---

App Router의 라우팅 기본 원리

일반 폴더는 URL 세그먼트를 만들고, 해당 위치의 page.tsx가 페이지 UI를 공개합니다. 자체 page.tsx가 없는 상위 폴더도 하위 경로의 세그먼트가 될 수 있습니다. 응답 전용 엔드포인트는 route.ts로 정의하며, 라우트 그룹과 private folder 같은 예외는 다음 장에서 살펴봅니다.

• 루트 라우트: src/app/page.tsx
• 중첩 라우트: src/app/dashboard/page.tsx -> /dashboard
• 동적 라우트: src/app/products/[id]/page.tsx -> /products/123 (여기서 [id]는 동적인 값)

이러한 구조를 통해 Next.js는 라우트 세그먼트별로 독립적인 레이아웃, 로딩 UI, 에러 UI를 정의할 수 있게 합니다.

예시

루트의 별도 app/이나 사용자 정의 rewrite 없이 다음 파일을 가진 프로젝트를 생각해 봅니다. URL을 만들 때 src/app과 마지막 page.tsx는 주소에 넣지 않습니다. 정적 파일에서는 public 접두사를 빼고 그 안의 경로를 사용합니다.

/catalog/utils.ts로 요청해도 이 TypeScript 소스가 자동으로 내려오지는 않습니다. 반대로 공개할 정적 파일을 public에 넣으면 그 경로로 제공된다는 차이를 기억합니다. 파일 배치와 공개 경계

경로를 바꾸어 판단하기

src/app/reports/2026/page.tsx, src/app/reports/loading.tsx, public/docs/guide.pdf만 추가했습니다. reports 자체의 page.tsx와 route.ts는 없습니다. 새 페이지와 PDF의 URL을 쓰고, /reports가 독립 페이지가 되는지 설명하세요.

경로 도출 과정

페이지는 /reports/2026, PDF는 /docs/guide.pdf입니다. 상위 reports는 자식 URL에 포함되지만 그 위치에 페이지 진입점이 없으므로 이 조건의 /reports 자체는 페이지가 아닙니다. loading.tsx는 로딩 UI를 지원하는 특수 파일이며 단독으로 페이지 URL을 만들지 않습니다.