2nd/10_Wiki/Topics_Dev/Next.js Modular and Scalable Project Structure.md

# [[Next.js Modular and Scalable Project Structure|Next.js Modular and Scalable Project Structure]]

## 📌Brief 단기 요약
[[Next.js|Next.js]]의 모듈화되고 확장 가능한 프로젝트 구조는 애플리케이션이 커짐에 따라 코드를 파일 유형이 아닌 기능(Feature)이나 도메인(Domain)을 중심으로 구성하여 유지보수성을 극대화하는 아키텍처 패턴입니다 [1, 2]. `app/` 디렉토리는 오직 라우팅과 레이아웃 관리에만 사용하고, 핵심 비즈니스 로직과 UI 컴포넌트는 `src/features/` 등에 분리하여 캡슐화합니다 [1, 3]. 이 구조는 대규모 프로젝트에서 UI, 비즈니스 로직, CSS 관리를 체계화하여 기술 부채를 줄이고 팀 간 협업 효율을 높이는 데 필수적입니다 [2, 4].

## 📖 Core Content
- **기능/도메인 주도 아키텍처 ([[Feature-Driven Architecture|Feature-Driven Architecture]]):** 
  컴포넌트, 훅(hooks), 유틸리티를 파일 유형별로 묶는 대신, 실제 애플리케이션의 도메인(예: `market-data`, `user-profile` 등)을 기반으로 `features/` 디렉토리에 그룹화해야 합니다 [1-3]. 이 방식을 채택하면 전역 컴포넌트 폴더가 비대해지는 것을 방지할 수 있으며, 특정 기능에 버그가 발생했을 때 정확히 어느 폴더를 확인해야 하는지 알 수 있어 캡슐화와 유지보수성이 크게 향상됩니다 [3, 4].

- **앱 라우터와 비즈니스 로직의 명확한 분리:** 
  Next.js의 `app/` 폴더 내 파일들(예: `page.tsx`, `layout.tsx`)은 라우팅, 메타데이터 생성, 검색 매개변수([[Search|Search]] params) 처리 등 Next.js 고유의 기능만 담당하도록 단순하게 유지해야 합니다 [1, 3]. 실제 데이터 패칭(fetching)과 프레젠테이션 계층 등 비즈니스 로직은 라우트와 섞이지 않도록 외부 폴더로 분리합니다 [3, 5].

- **재사용 가능한 컴포넌트 및 CSS 시스템 통합:** 
  대규모 시스템에서는 Storybook과 같은 툴을 사용해 문서화된 재사용 가능한 컴포넌트 시스템을 구축하는 것이 좋습니다 [5]. 특히 [[Next.js App Router|Next.js App Router]]를 사용할 경우, 기존의 런타임 CSS-in-JS(예: styled-components, Emotion)는 [[React Server Components|React Server Components]](RSC)와 본질적으로 호환되지 않습니다 [6]. 따라서 모듈화된 프로젝트 구조에서는 성능과 호환성을 위해 Tailwind CSS, [[CSS Modules|CSS Modules]] 또는 빌드 타임에 정적 CSS를 생성하는 [[vanilla-extract|vanilla-extract]] 방식을 채택하는 것이 권장됩니다 [7, 8]. 

- **확장성을 위한 설정 및 규칙 ([[Scalability|Scalability]] Practices):**
  - **절대 경로(Absolute Imports) 사용:** `../../../components/Button`과 같은 복잡한 경로 대신 `tsconfig.json`의 경로 별칭(path aliases)을 활용하여 `@/components/ui/Button`처럼 깔끔하게 코드를 유지합니다 [4, 9, 10].
  - **API 및 상태 관리 중앙화:** 네트워크 로직(API 호출)은 기능(feature)별 서비스 폴더에 중앙 집중화하여 프론트엔드와 백엔드를 깔끔하게 디커플링합니다 [3, 5, 9]. 전역 상태 관리는 최소화하되, 앱 규모에 따라 [[Context API|Context API]]에서 Zustand, 그리고 Redux Toolkit으로 확장합니다 [11].
  - **디렉토리 분리:** 최상위 폴더가 설정 파일들(`tailwind.config.ts`, `next.config.mjs` 등)로 어질러지는 것을 막기 위해 `src/` 디렉토리를 사용하는 것이 좋습니다 [10].

## 🔗 Knowledge Connections
- **Related Topics:** [[CSS Modules|CSS Modules]], Tailwind 전략, 실무에서 CSS 관리하는 방법, [[디자인 시스템 개념|디자인 시스템 개념]]
- **Projects/Contexts:** 대규모 프론트엔드 프로젝트 아키텍처 구축, React [[Server Components|Server Components]] 기반 App Router 마이그레이션
- **Contradictions/Notes:** 컴포넌트 단위 스타일링을 위해 CSS-in-JS 방식을 선호할 수 있으나, Next.js의 현대적인 App Router 환경(RSC)에서는 성능 저하 및 호환성 문제로 인해 런타임 CSS-in-JS의 사용이 강하게 제한되며, 대신 CSS Modules나 Tailwind CSS가 더 안전한 대안으로 주장되고 있습니다 [6, 8].

---
*Last updated: 2026-04-26*