# [[Frontend Folder Structure]]

## 📌 Brief Summary
프론트엔드 폴더 구조(Frontend Folder Structure)는 리액트(React)를 비롯한 애플리케이션의 유지보수성, 확장성, 협업 효율성을 결정짓는 핵심 아키텍처 요소입니다 [1-3]. 과거의 파일 유형(File-Type) 중심의 구조에서 벗어나 비즈니스 기능(Feature) 및 도메인을 중심으로 모듈화하는 방식이 권장됩니다 [4, 5]. 이를 통해 코드 결합도를 낮추고 응집도를 높여 복잡한 시스템에서도 예측 가능성을 유지하고 기술 부채를 방지할 수 있습니다 [5-7].

## 📖 Core Content
- **폴더 구조의 중요성**: 체계적이지 않은 구조는 코드를 얽히게 만들고 디버깅과 테스트를 어렵게 하여 결과적으로 기술 부채를 유발합니다 [1, 8, 9]. 반면 잘 설계된 프로젝트는 UI 요소, 비즈니스 로직, 상태 관리를 명확하게 분리(Separation of Concerns)하여 모듈의 재사용성과 협업 효율성을 크게 높여줍니다 [3, 9].
- **기존 폴더 구조 접근법과 한계**:
  - **단일(Flat) 구조**: 소규모 애플리케이션에 적합하게 모든 파일을 루트 레벨 근처에 배치하는 방식으로, 프로젝트가 커지면 관리와 확장이 불가능에 가깝습니다 [10].
  - **파일 유형 기반(File-Type Based)**: `components`, `hooks`, `services` 등 기술적 역할에 따라 폴더를 나누는 전통적 방식입니다(예: MVC 패턴). 기능이 복잡해질수록 하나의 기능을 수정하기 위해 여러 폴더를 넘나들어야 하므로 확장성이 현저히 떨어집니다 [4, 11, 12].
- **기능 기반 구조(Feature-Based Structure)**: 2025년 기준 모던 프론트엔드 개발에서는 비즈니스 기능을 중심으로 폴더를 분리하는 방식이 권장됩니다 [5]. 예를 들어 `src/features/auth` 폴더 내부에 인증과 관련된 컴포넌트, 훅(Hooks), API 통신 로직, 타입을 모두 캡슐화하여 독립적인 모듈로 관리합니다 [13, 14].
- **권장되는 하이브리드 디렉토리 구성** [5, 14-23]:
  - `/assets`: 이미지, 폰트 등 정적 미디어 리소스.
  - `/components`: 애플리케이션 전체에서 공유되는 재사용 가능한 UI 컴포넌트 (버튼, 모달 등).
  - `/features`: 핵심 기능 및 도메인 로직이 응집된 독립 모듈.
  - `/hooks` 및 `/utils`: 전역적으로 공유되는 커스텀 훅과 범용 유틸리티 함수.
  - `/services` (또는 `/api`): 외부 서버와의 통신 및 서드파티 서비스 연동 로직.
  - `/store` (또는 `/context`): Redux, Zustand 등을 활용한 전역 상태 관리 인프라.
  - `/pages` 및 `/layouts`: 라우팅에 매핑되는 페이지 화면 및 공통 레이아웃 컴포넌트.
- **FSD (Feature-Sliced Design) 방법론**: 기능 기반 설계를 한 단계 더 체계화한 아키텍처로, 프론트엔드 프로젝트를 `app`, `pages`, `widgets`, `features`, `entities`, `shared`라는 6가지 계층(Layer)으로 나눕니다 [24-26]. 
  - 상위 계층이 하위 계층에만 의존해야 하는 '단방향 의존성' 규칙을 강제하여 순환 참조를 방지합니다 [24].
  - 각 슬라이스(Slice)는 반드시 `index.ts`를 통해 정의된 퍼블릭 API(Public API)만 외부에 노출하여 내부 구현을 철저히 캡슐화하고 안전한 리팩토링을 보장합니다 [24, 27, 28].
- **네이밍 컨벤션과 거버넌스(Naming & Governance)**: 구조화와 더불어 일관된 네이밍 규칙은 필수입니다. 파일 및 폴더 이름에는 운영체제 간 호환성을 위해 `kebab-case`를 사용하거나 리액트 컴포넌트에 맞춰 `PascalCase`를 주로 사용하며, 변수나 함수, 훅은 `camelCase`를 준수해야 합니다 [29-34]. 또한 ESLint와 같은 도구를 사용해 이러한 아키텍처 및 네이밍 규칙 위반을 자동 검사(Linting)하도록 설정하는 것이 모범 사례입니다 [30].

## 🔗 Knowledge Connections
- **Related Topics:** [[Feature-Sliced Design (FSD)]], [[Clean Code Principles]], [[State Management]]
- **Projects/Contexts:** [[Scalable React Applications]], [[Next.js File Naming and Routing]]
- **Contradictions/Notes:** 컴포넌트, 훅, 서비스 등의 파일 유형에 따라 그룹화하는 방식(File-Type Based)은 직관적이라 초기 개발이나 초보자가 접근하기는 쉽지만, 애플리케이션의 규모가 확장되고 도메인 로직이 복잡해질 경우에는 기능(Feature) 기반 구조에 비해 유지보수성과 생산성이 크게 떨어지며 스파게티 코드를 유발하는 원인이 됩니다 [7, 11, 12].

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