안동민 개발노트

Next.js 15 프로젝트를 성공적으로 생성하고 실행하셨으니, 이제 우리가 앞으로 작업하게 될 프로젝트의 내부 구조를 좀 더 깊이 있게 이해하는 시간을 가져보겠습니다. 프로젝트의 각 디렉터리와 파일이 어떤 역할을 하는지 알면, 코드를 작성하고 관리하는 데 훨씬 수월해집니다.

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

주요 디렉터리 및 파일

Next.js 프로젝트의 핵심은 src 디렉터리 안에 있는 app 디렉터리입니다. 이 외에도 몇 가지 중요한 최상위 디렉터리와 파일들이 있습니다.

`src/` 디렉터리

프로젝트의 소스 코드가 위치하는 곳입니다. create-next-app에서 src/ 디렉터리 사용을 선택했다면, 모든 애플리케이션 코드는 이 안에 작성됩니다.

`src/app/` 디렉터리 (App Router의 핵심)

이 디렉터리는 Next.js 15의 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/my-image.png 파일은 /my-image.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 등을 정의할 수 있는 강력한 기능을 제공합니다.

프로젝트 구조 이해하기