Next.js 루트 구조 완벽 정리 (App Router 기준)
Next.js를 처음 접하거나, 최신 버전(App Router)을 사용하려고 할 때 프로젝트 루트 구조를 이해하는 건 정말 중요합니다.
이번 글에서는 Next.js 기본 디렉터리 구조를 App Router 기준으로 체계적으로 설명합니다.
1. 최상단 구조
Next.js 프로젝트를 생성하면 기본적으로 다음과 같은 루트 구조를 갖습니다.
my-next-app/
├── app/
├── public/
├── node_modules/
├── .next/
├── package.json
├── next.config.js
├── tsconfig.json / jsconfig.json
└── README.md주요 폴더와 파일 설명
| 이름 | 설명 |
|---|---|
app/ | App Router 기반 라우팅 및 페이지 구성 폴더 |
public/ | 정적 파일(이미지, 폰트 등)을 넣는 곳 |
node_modules/ | 프로젝트 의존성 모듈 |
.next/ | Next.js가 빌드할 때 생성하는 폴더 (자동 관리) |
package.json | 프로젝트 설정과 의존성 관리 |
next.config.js | Next.js 전용 설정 파일 |
tsconfig.json | (TypeScript 사용 시) 타입스크립트 설정 파일 |
README.md | 프로젝트 설명 파일 |
2. app/ 폴더 - 새로운 App Router의 핵심
Next.js 13부터 새롭게 추가된 app/ 폴더는 파일 기반 라우팅의 중심입니다.
이 안에 페이지, 레이아웃, 템플릿 등을 구성합니다.
예시:
app/
├── layout.tsx
├── page.tsx
├── globals.css
├── about/
│ ├── page.tsx
│ └── layout.tsx
├── blog/
│ ├── [slug]/
│ │ └── page.tsx
│ └── page.tsx
└── api/
└── hello/
└── route.tsapp/ 폴더 주요 규칙
| 파일/폴더 | 역할 |
|---|---|
page.tsx | 하나의 페이지(=URL 경로)로 렌더링 |
layout.tsx | 페이지에 공통으로 적용할 레이아웃 |
template.tsx | 매번 새로운 인스턴스를 렌더링하는 레이아웃 |
error.tsx | 해당 라우트 에러 처리 |
loading.tsx | 해당 라우트 로딩 상태 처리 |
not-found.tsx | 404 페이지 |
api/ | API 라우트를 만드는 폴더 (route.ts 필수) |
3. public/ 폴더
- 이 폴더 안에 넣은 파일은 / 경로 기준으로 접근할 수 있습니다.
- 예:
/public/images/logo.png→https://yourdomain.com/images/logo.png
주의: next/image처럼 최적화된 이미지 컴포넌트를 사용할 경우에는 import 방식으로 가져와야 하고,
정적 파일만 public/에 두어야 합니다.
4. 프로젝트 설정 파일
| 파일명 | 설명 |
|---|---|
next.config.js | Next.js 커스터마이징 설정 (리다이렉트, 이미지 도메인, 플러그인 등) |
package.json | npm/yarn 관리, 스크립트, 의존성 명시 |
tsconfig.json | TypeScript 설정 (JS 사용시 jsconfig.json) |
5. 빌드 및 런타임 폴더
| 폴더 | 설명 |
|---|---|
.next/ | 빌드 시 자동 생성, 서버/클라이언트 번들 파일 저장 |
node_modules/ | 설치된 모든 외부 패키지 저장소 |
TIP: .next/와 node_modules/는 직접 수정하지 않습니다. (Git에도 보통 제외합니다.)
6. 추가로 알면 좋은 것
middleware.ts: 요청(Request) 가로채기 및 처리 (예: 인증 리다이렉트)env파일 :.env.local,.env.production등으로 환경변수 관리components/폴더 : UI 컴포넌트 모듈화lib/,hooks/,utils/폴더 : 재사용 가능한 함수 및 로직 정리
Pages Router vs App Router
Next.js 13부터 App Router가 등장했지만, 기존 Pages Router도 여전히 사용 가능합니다.
둘의 차이를 간단히 비교해봅니다.
| 항목 | Pages Router (pages/) | App Router (app/) |
|---|---|---|
| 폴더명 | pages/ | app/ |
| 라우팅 방식 | 파일 기반 라우팅 | 파일 기반 + 컴포넌트 기반 레이아웃 |
| 레이아웃 | _app.js, _document.js | layout.tsx, template.tsx (라우트별 레이아웃 지원) |
| 데이터 패칭 | getServerSideProps, getStaticProps | fetch(), useEffect, 서버 컴포넌트(Server Components) |
| 클라이언트 컴포넌트 표시 | 기본 클라이언트 컴포넌트 | use client 지시어 필요 |
| 서버 컴포넌트 | 지원 안 함 | 기본적으로 서버 컴포넌트 지원 |
| 사용 시기 | 빠르게 만들거나, 레거시 프로젝트 유지 | 새로운 프로젝트, 서버 컴포넌트 적극 사용 시 |
| 학습 난이도 | 쉬움 | 약간 복잡하지만 확장성 높음 |
✅ 정리:
- 빠르게 MVP를 만들거나 익숙한 구조를 원하면 Pages Router
- 서버 컴포넌트, 고성능 최적화를 활용하고 싶다면 App Router
마치며
Next.js의 루트 구조를 정확히 이해하면,
대규모 프로젝트도 깔끔하게 관리할 수 있습니다.
특히 App Router를 쓴다면, "페이지 중심" 이 아닌 "레이아웃 중심" 설계에 익숙해지는 게 정말 중요합니다.
지금부터 천천히 구조를 잡아가보세요!
Mee-