# [[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*