Next.js 기준 표준 파일 구조

Next.js 15 버전 이상에서 선호되는 라우터 방식은 App Router입니다.

App Router는 Next.js의 새로운 라우팅 시스템으로, 기존의 Pages Router를 대체하며 다음과 같은 특징을 가집니다:

1. app/ 디렉토리를 사용하여 라우팅을 구성합니다.
2. 폴더 기반 라우팅을 채택하여 더 직관적인 구조를 제공합니다.
3. React Server Components를 기본적으로 지원합니다.
4. 레이아웃 구성이 더 유연해졌으며, layout.js 파일을 통해 중첩 레이아웃을 쉽게 구현할 수 있습니다.
5. 서버 중심 라우팅을 채택하여 성능 최적화에 중점을 둡니다.

App Router는 Pages Router에 비해 더 강력한 기능을 제공하며, Next.js의 미래 방향성을 대표합니다. 따라서 새로운 프로젝트를 시작할 때는 App Router 방식을 사용하는 것이 권장됩니다.

다만, App Router가 아직 완전히 성숙하지 않아 일부 성능 이슈가 있을 수 있으므로, 프로젝트의 요구사항과 팀의 숙련도를 고려하여 선택하는 것이 중요합니다.

 

app/
├── (main)/                  # 메인 사이트 라우트 그룹
│   ├── layout.tsx           # 네비게이션이 포함된 메인 레이아웃
│   ├── page.tsx             # 홈페이지 (URL: /)
│   ├── about/               # 소개 페이지
│   │   └── page.tsx         # (URL: /about)
│   ├── blog/                # 블로그 섹션
│   │   ├── page.tsx         # 블로그 목록 페이지 (URL: /blog)
│   │   └── [slug]/          # 동적 블로그 포스트 라우트
│   │       └── page.tsx     # 단일 블로그 포스트 페이지 (URL: /blog/post-slug)
│   ├── contact/             # 연락처 페이지
│   │   └── page.tsx         # (URL: /contact)
│   └── products/            # 제품 섹션
│       ├── page.tsx         # 제품 목록 페이지 (URL: /products)
│       └── [id]/            # 동적 제품 라우트
│           └── page.tsx     # 단일 제품 페이지 (URL: /products/123)
│
├── (auth)/                  # 인증 관련 라우트 그룹
│   ├── layout.tsx           # 네비게이션이 없는 인증 전용 레이아웃
│   ├── login/
│   │   └── page.tsx         # 로그인 페이지 (URL: /login)
│   ├── signup/
│   │   └── page.tsx         # 회원가입 페이지 (URL: /signup)
│   ├── forgot-password/
│   │   └── page.tsx         # 비밀번호 찾기 페이지 (URL: /forgot-password)
│   └── reset-password/
│       └── [token]/
│           └── page.tsx     # 비밀번호 재설정 페이지 (URL: /reset-password/token)
│
├── (dashboard)/             # 대시보드 라우트 그룹 (로그인 필요)
│   ├── layout.tsx           # 대시보드 전용 레이아웃 (사이드바 등)
│   ├── dashboard/
│   │   └── page.tsx         # 대시보드 메인 페이지 (URL: /dashboard)
│   ├── settings/
│   │   └── page.tsx         # 사용자 설정 페이지 (URL: /settings)
│   └── profile/
│       └── page.tsx         # 사용자 프로필 페이지 (URL: /profile)
│
├── api/                     # API 라우트
│   ├── auth/
│   │   └── [...nextauth]/
│   │       └── route.ts     # NextAuth.js 인증 API 라우트
│   └── products/
│       └── route.ts         # 제품 관련 API 라우트
│
├── components/              # 공통 컴포넌트
│   ├── ui/                  # UI 컴포넌트
│   │   ├── Button.tsx
│   │   ├── Card.tsx
│   │   ├── Input.tsx
│   │   └── Modal.tsx
│   ├── layout/              # 레이아웃 관련 컴포넌트
│   │   ├── Footer.tsx
│   │   ├── Header.tsx
│   │   ├── Navigation.tsx
│   │   └── Sidebar.tsx
│   └── features/            # 기능별 컴포넌트
│       ├── auth/
│       │   ├── LoginForm.tsx
│       │   └── SignupForm.tsx
│       └── products/
│           ├── ProductCard.tsx
│           └── ProductList.tsx
│
├── hooks/                   # 커스텀 훅
│   ├── useAuth.ts
│   ├── useForm.ts
│   └── useLocalStorage.ts
│
├── lib/                     # 유틸리티 함수 및 서비스
│   ├── db.ts                # 데이터베이스 연결
│   ├── auth.ts              # 인증 관련 유틸리티
│   └── utils.ts             # 기타 유틸리티 함수
│
├── actions/                 # Server Actions
│   ├── auth.ts              # 인증 관련 액션
│   ├── products.ts          # 제품 관련 액션
│   └── users.ts             # 사용자 관련 액션
│
├── types/                   # TypeScript 타입 정의
│   ├── auth.ts
│   ├── product.ts
│   └── user.ts
│
├── public/                  # 정적 파일
│   ├── favicon.ico
│   ├── logo.svg
│   └── images/
│       └── ...
│
├── styles/                  # 스타일 관련 파일 (옵션)
│   └── theme.ts             # 테마 설정
│
├── layout.tsx               # 루트 레이아웃 (폰트, 메타데이터 등)
├── globals.css              # 전역 CSS
├── not-found.tsx            # 404 페이지
├── loading.tsx              # 로딩 UI
├── error.tsx                # 에러 UI
└── middleware.ts            # 미들웨어 (인증 체크 등)

 

주요 특징과 장점은 다음과 같습니다

1. 라우트 그룹 구성

• (main): 일반 사용자가 접근할 수 있는 메인 사이트 페이지들(홈, 블로그, 제품 등)
• (auth): 네비게이션이 없는 인증 관련 페이지들(로그인, 회원가입 등)
• (dashboard): 로그인한 사용자를 위한 대시보드 페이지들(설정, 프로필 등)

2. 컴포넌트 구조

• components/ui: 재사용 가능한 UI 컴포넌트(버튼, 카드, 인풋 등)
• components/layout: 레이아웃 관련 컴포넌트(헤더, 풋터, 네비게이션 등)
• components/features: 기능별 컴포넌트(로그인 폼, 제품 카드 등)

3. 데이터 관리

• actions: Server Actions 정의
• lib: 유틸리티 함수 및 서비스
• hooks: 재사용 가능한 커스텀 훅
• types: TypeScript 타입 정의

4. 특별 레이아웃

• 각 라우트 그룹에 맞는 독립적인 레이아웃 적용
• 루트 레이아웃에서는 폰트, 메타데이터 등 공통 요소만 정의

5. 엣지 케이스 처리

• 404 페이지, 로딩 UI, 에러 UI 등 포함

이 구조의 장점:

1. 확장성: 기능이 추가되어도 구조가 복잡해지지 않음
2. 분리된 관심사: 각 기능과 UI 요소가 명확히 분리됨
3. 재사용성: 컴포넌트와 훅을 쉽게 재사용할 수 있음
4. 유지보수성: 파일 위치를 쉽게 예측할 수 있음
5. 일관성: 전체 애플리케이션에 걸쳐 일관된 스타일과 동작 보장

프로젝트 규모에 따라 이 구조를 간소화하거나 확장할 수 있습니다. 예를 들어, 소규모 프로젝트에서는 일부 폴더를 통합하거나 생략할 수 있습니다.