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

Next.js Modular and Scalable Project Structure

📌Brief 단기 요약

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

📖 Core Content

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

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

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

• 확장성을 위한 설정 및 규칙 (Scalability Practices):

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

🔗 Knowledge Connections

• Related Topics: CSS Modules, Tailwind 전략, 실무에서 CSS 관리하는 방법, 디자인 시스템 개념
• Projects/Contexts: 대규모 프론트엔드 프로젝트 아키텍처 구축, React 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