2nd/00_Raw/React Project Structure.md

React Project Structure

📌 Brief Summary

React 애플리케이션은 기본적으로 아키텍처나 폴더 구조를 강제하지 않기 때문에, 프로젝트가 확장됨에 따라 구조 관리가 필수적입니다 [1]. 유지보수성, 확장성, 협업의 효율성을 높이기 위해 프론트엔드 생태계는 과거의 파일 유형 기반 구조에서 기능(Feature) 또는 도메인 기반의 구조로 전환되었습니다 [2, 3]. 특히 2025년 기준으로는 모듈화와 관심사 분리를 강조하는 하이브리드 폴더 구조와 Feature-Sliced Design(FSD)과 같이 캡슐화와 단방향 의존성을 강제하는 체계적인 방법론이 권장되고 있습니다 [4-7].

📖 Core Content

• 폴더 구조의 중요성

  • 구조가 명확하지 않은 대규모 React 앱은 비즈니스 로직이 UI 컴포넌트로 누수되거나 상태 소유권이 불분명해지는 등 아키텍처 붕괴(Architectural Collapse)를 겪기 쉽습니다 [1, 8].
  • 잘 구성된 폴더 구조는 파일의 목적을 명확히 하여 빠른 파일 탐색을 돕고, 예측 가능성을 높이며, 디버깅을 용이하게 하여 장기적인 기술 부채를 줄여줍니다 [9-11].

• 구조의 발전 및 주요 접근 방식

  • 파일 유형 기반 구조 (File-Type Based Structure): 컴포넌트, 훅, 스타일 등을 각각의 역할별 폴더(/components, /hooks 등)에 모아두는 고전적인 방식입니다 [2, 12, 13]. 작은 규모에서는 직관적이지만, 앱이 커지면 특정 기능을 수정하기 위해 전체 디렉토리를 탐색해야 하므로 확장성이 크게 떨어집니다 [2, 12, 13].
  • 기능 기반 구조 (Feature-Based Structure): 비즈니스 도메인이나 기능(예: auth, dashboard)을 중심으로 관련된 컴포넌트, 훅, API, 타입을 하나의 폴더에 캡슐화하여 독립적인 모듈처럼 다루는 방식입니다 [3, 14, 15]. 이는 높은 응집도와 명확한 경계를 제공하여 확장에 유리합니다 [3, 15].
  • 2025년 권장 하이브리드 구조: 전역 공유 요소와 기능별 요소를 균형 있게 분리합니다. 주로 /src 디렉토리 하위에 재사용 가능한 /components, 도메인 로직을 캡슐화한 /features, 공통 /hooks, /pages(라우트), 외부 통신용 /services, 전역 상태용 /store, 유틸리티 함수용 /utils 등으로 구성됩니다 [16-25].

• Feature-Sliced Design (FSD)

  • 대규모 React 애플리케이션을 위해 설계된 현대적인 아키텍처 방법론으로, 컴포넌트 기반 개발, 도메인 주도 설계(DDD), 모듈식 시스템의 장점을 결합했습니다 [4, 26].
  • 단방향 의존성 계층: shared(공통 유틸/UI) \rightarrow entities(비즈니스 모델) \rightarrow features(사용자 상호작용) \rightarrow widgets(조합된 UI 블록) \rightarrow pages(화면) \rightarrow app(전역 설정) 순으로 계층을 나누며, 하위 계층은 상위 계층을 import 할 수 없도록 엄격히 통제합니다 [5, 14, 27].
  • Public API 규칙: 각 슬라이스는 단일 진입점(index.ts)만을 노출하며 내부 구현은 숨깁니다. 이를 통해 의도치 않은 결합(Coupling)을 방지하고 안전한 리팩토링을 보장합니다 [28, 29].

🔗 Knowledge Connections

• Related Topics: Feature-Sliced Design (FSD), Domain-Driven Design, Clean Code
• Projects/Contexts: Scalable Frontend Systems, React Development
• Contradictions/Notes: 기능 기반 구조나 FSD 방법론은 대규모 애플리케이션의 유지보수와 확장을 위해서는 필수적이고 훌륭한 해결책이지만 [4, 30], 매우 단순한 소규모 프로젝트나 초보자에게는 디렉토리 구조 설정이 불필요하게 복잡한 오버킬(overkill)이 될 수 있으며 초기 학습 곡선이 요구됩니다 [30-32].

---

Last updated: 2026-04-26