Next.js 폴더 구조 및 아키텍처 설계 전략 – 유지보수성과 협업을 고려한 실전 가이드

Next.js 앱에서 폴더 구조 및 코드 아키텍처 설계 전략 – 유지보수성과 확장성을 고려한 실전 가이드

Next.js로 앱을 개발할 때 초기에 아무렇게나 구조를 짜면, 프로젝트가 커질수록 코드가 얽히고 설켜 유지보수가 힘들어집니다.

 

Next.js 폴더 구조 및 아키텍처 설계 전략 – 유지보수성과 협업을 고려한 실전 가이드

 

이번 글에서는 Next.js 앱을 처음부터 잘 설계하고, 협업, 테스트, 기능 확장까지 고려한 폴더 구조와 아키텍처 전략을 소개합니다.

• ✅ App Router vs Pages Router 구조 설계
• ✅ 폴더 네이밍 및 depth 기준
• ✅ 컴포넌트 분리 전략 (UI/Container/Feature)
• ✅ 상태관리, API, 유틸리티 위치
• ✅ 실전 예시와 팀 기반 아키텍처 패턴

---

1. 📂 Next.js 폴더 구조 기본 이해

✅ App Router vs Pages Router 비교

기능	Pages Router	App Router
기반 디렉토리	/pages	/app
라우팅 방식	파일 기반	폴더 + 파일 조합
레이아웃	각 페이지 독립	중첩 레이아웃 가능
서버 컴포넌트	불가	기본 지원 (React Server Component)

➡️ App Router는 Next.js 13 이후 공식 권장 구조이며, 대규모 앱, SSR 기반 서비스에 적합합니다.

---

2. 🧱 기본 폴더 구조 예시 (App Router 기준)

/app
  ├── layout.tsx
  ├── page.tsx
  ├── dashboard/
  │    ├── layout.tsx
  │    ├── page.tsx
  │    └── settings/
  │         └── page.tsx
  ├── login/
  │    └── page.tsx

/src
  ├── components/
  ├── features/
  ├── hooks/
  ├── lib/
  ├── services/
  ├── store/
  ├── styles/
  └── types/

✅ 핵심 역할

• /app: 라우팅 및 페이지 구조
• /components: 공통 UI 컴포넌트
• /features: 도메인 기능별 폴더
• /lib: 외부 유틸리티, API client
• /services: API 요청 모듈
• /store: 상태 관리 (예: Zustand, Redux 등)

3. 🧩 컴포넌트 분리 전략 – UI, 기능, 컨테이너 구분

✅ 컴포넌트의 분리 기준

• UI 컴포넌트: 디자인/뷰 중심, props만 받음
• Container 컴포넌트: 상태, 비즈니스 로직 포함
• Feature 컴포넌트: 특정 도메인 기능 단위 (예: LoginForm, ProductCard)

📦 구조 예시

/components
  ├── ui/
  │    ├── Button.tsx
  │    └── Input.tsx
  ├── layout/
  │    ├── Header.tsx
  │    └── Sidebar.tsx

/features
  ├── auth/
  │    ├── LoginForm.tsx
  │    └── SignupForm.tsx
  ├── post/
  │    ├── PostList.tsx
  │    └── PostCard.tsx

➡️ 이 구조는 재사용성과 역할 명확성을 높여줍니다.

---

4. 🔗 상태 관리 계층의 위치 – 전역 vs 로컬 vs 서버

✅ 상태 관리의 세 가지 범위

• Local state: useState, useReducer
• Global state: Zustand, Redux, Jotai 등
• Server state: React Query, SWR 등

📌 상태 저장소 위치

/store
  ├── auth.ts
  ├── user.ts
  └── modal.ts

✅ 추천: 도메인 단위로 쪼개서 저장

• 기능이 커질수록 전역 상태도 모듈화 필요
• 공통 상태는 /store/common.ts 처럼 구분

🧠 팁

• 상태는 최소한으로 전역화해야 합니다
• 가능하면 컴포넌트 내에 국소화된 상태 우선

---

5. 🌐 API 계층 설계 – 네트워크 분리와 모듈화

✅ 폴더 구조 예시

/services
  ├── apiClient.ts
  ├── auth.ts
  ├── post.ts

✅ axios 인스턴스 분리

// apiClient.ts
import axios from 'axios';

const apiClient = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL,
  withCredentials: true,
});

export default apiClient;

✅ 서비스별 API 함수 분리

// services/auth.ts
import apiClient from './apiClient';

export const login = (data) => apiClient.post('/auth/login', data);
export const logout = () => apiClient.post('/auth/logout');

➡️ API 호출과 비즈니스 로직을 컴포넌트에서 분리해 테스트 용이성과 유지보수성을 크게 높일 수 있습니다.

6. 🧭 디렉토리 depth 기준 – 언제 나눌 것인가?

✅ 깊이를 나누는 기준

• 파일 수가 5개 이상이거나
• 두 개 이상의 하위 역할(예: 컴포넌트 + 스타일)이 생기면 분리

📌 구조 예시

/features/product
  ├── components/
  │    ├── ProductList.tsx
  │    └── ProductCard.tsx
  ├── hooks/
  │    └── useProducts.ts
  ├── services/
  │    └── productApi.ts
  └── types/
       └── product.ts

➡️ 폴더 depth는 무조건 얕게 만드는 것보다, 의미 단위로 쪼개서 역할이 명확해지게 만드는 것이 중요합니다.

---

7. 🧾 네이밍 규칙 – 통일감은 생산성과 직결된다

✅ 컴포넌트 네이밍

• PascalCase 사용 (예: ProductCard.tsx)
• 폴더명과 컴포넌트명이 동일할 경우 → index.tsx 권장

/features/login/LoginForm/index.tsx

✅ 상태, 훅, API 네이밍

• use[기능명]: useAuth, usePost
• [기능]Store: authStore, modalStore
• [기능]Api: userApi, postApi

✅ 파일명 규칙

• 전역은 kebab-case 또는 camelCase 혼용 가능
• 폴더와 파일은 동일한 기준 유지

---

8. 👥 팀 협업을 위한 아키텍처 가이드

✅ 팀 프로젝트에서 자주 발생하는 문제

• 각자 다른 방식의 컴포넌트 구조
• 중복된 API 호출 함수
• 전역 상태가 한곳에 몰림

✅ 협업 시 필수 정리 항목

1. 공식 폴더 구조 문서 작성
2. 컴포넌트 작성 규칙 공유 (예: props, 로딩, 에러 처리 방식)
3. 상태 저장 위치 기준 설정
4. 공통 API, UI, 훅 분리 방식 명시

📌 Lint & Convention 도구 추천

• eslint, prettier
• absolute import 설정 (@/components 등)

// tsconfig.json
"paths": {
  "@/components/*": ["src/components/*"],
  "@/features/*": ["src/features/*"]
}

➡️ 경로, 폴더, 상태 설계까지 일관되게 관리하면 누가 코드를 짜도 읽기 쉬운 구조가 완성됩니다.

---

🧠 마무리 – 설계가 곧 생산성이다

✅ 핵심 요약

• App Router 구조에 맞게 폴더와 기능을 모듈화
• UI/Feature/Container 단위로 컴포넌트 구분
• 상태와 API는 도메인 단위로 분리
• 네이밍과 구조 규칙은 팀과 공유

✅ 실무에서의 팁

• 모든 기능은 작고 독립된 단위로
• 사용자 UX와 유지보수를 함께 고려한 설계
• 폴더 구조도 UI의 일관성처럼 '디자인'해야 함

---

 

긴 글 읽어주셔서 감사합니다! 공감, 댓글, 공유로 응원해주시면 다음 글 제작에 큰 힘이 됩니다 🙌