2nd/10_Wiki/Topics/Folder Structure Best Practices.md

Folder Structure Best Practices

📌 Brief Summary

React 등 프론트엔드 프로젝트에서 코드의 유지보수성, 확장성, 그리고 협업 효율성을 높이기 위해 파일과 디렉터리를 체계적으로 구성하는 방법론입니다 [1]. 현대적인 애플리케이션에서는 과거의 파일 유형 기반(유형별 분류) 구조에서 벗어나, 기능(Feature)이나 도메인 중심으로 관련된 로직을 묶는 하이브리드 또는 기능 기반 방식이 모범 사례로 권장됩니다 [2, 3]. 이를 통해 UI, 비즈니스 로직, 상태 관리 등의 관심사를 명확히 분리하고 프로젝트가 커짐에 따라 발생하는 기술 부채를 최소화할 수 있습니다 [4].

📖 Core 소스 Content

• 구조의 진화와 한계:
  • 초기 소규모 프로젝트는 주로 모든 컴포넌트를 components 폴더에, 모든 훅을 hooks 폴더에 넣는 플랫(Flat) 구조나 파일 유형 기반 구조로 시작합니다 [5, 6].
  • 하지만 앱의 규모가 커지면 단일 기능을 수정하기 위해 여러 폴더를 넘나들어야 하므로, 개발 속도가 느려지고 디버깅이 어려워지며 코드베이스가 복잡해지는 한계가 발생합니다 [3, 6, 7].
• 기능 기반(Feature-based) 및 하이브리드 구조:
  • 2025년 기준 가장 권장되는 접근 방식은 파일 유형이 아닌 비즈니스 기능이나 모듈을 중심으로 폴더를 구성하는 것입니다 [2, 8, 9].
  • 각 기능(Feature)은 캡슐화되어 다른 기능과 독립적으로 작동할 수 있으므로, 규모 확장 시 기존 코드에 영향을 주지 않고 새로운 기능을 매끄럽게 추가할 수 있습니다 [8, 10].
• 권장 디렉터리 구성 (src/ 하위):
  • assets/: 이미지, 폰트 등 정적 미디어 리소스 보관 [11, 12].
  • components/: 여러 기능에서 공통으로 재사용되는 도메인에 구애받지 않는 UI 요소 (예: 버튼, 모달, 네비게이션 바 등) [2, 12, 13].
  • features/ (또는 modules/): 인증(Auth), 대시보드(Dashboard) 등 도메인별 비즈니스 로직. 이 폴더 내부에는 해당 기능에만 쓰이는 컴포넌트, 훅, API 등을 캡슐화하여 보관합니다 [2, 9, 13].
  • hooks/: 폼 처리, 데이터 페칭 등 앱 전반에서 재사용 가능한 커스텀 훅 [9, 14].
  • pages/ (또는 routes/): 라우팅에 매핑되는 페이지 레벨 컴포넌트 [15, 16].
  • services/: 서드파티 서비스 연동이나 API 요청 등 외부 통신 로직 [16, 17].
  • store/ (또는 context/): Redux, Zustand, Context API를 활용하는 전역 상태 관리 로직 [14-16].
  • utils/: 날짜 포맷팅, 데이터 유효성 검사 등 상태를 가지지 않는 유틸리티 함수 [17, 18].
  • styles/: 글로벌 CSS, 테마(Theme) 등 전역 스타일링 파일 [18, 19].
  • types/: TypeScript 사용 시 전역으로 사용되는 타입 및 인터페이스 보관 [18].
  • config/: 환경 변수나 애플리케이션 전역 설정(API 기본 URL 등) 관리 [18, 20].
• Feature-Sliced Design (FSD):
  • 기능 기반 폴더 구조보다 더 엄격하게 의존성의 방향을 통제하는 프론트엔드 아키텍처 방법론입니다 [21].
  • shared -> entities -> features -> widgets -> pages -> app 이라는 고정된 다층 계층(Layer)을 가집니다 [22, 23].
  • 상위 계층은 하위 계층의 코드를 가져올 수 있지만(Import), 하위 계층은 상위 계층을 참조할 수 없는 단방향 의존성 규칙을 통해 순환 의존성을 방지합니다 [22, 24].
• Next.js 환경에서의 라우트 그룹 (Route Groups):
  • Next.js 프로젝트에서는 괄호를 사용한 폴더명 (folderName) 방식을 통해, 실제 URL 경로에는 영향을 주지 않으면서도 관련 기능이나 논리에 따라 라우트를 깔끔하게 그룹화할 수 있습니다 [25-27].

🔗 Knowledge Connections

Related Concepts

• Feature-Sliced Design

  • 연결 이유: 대규모 React 애플리케이션의 폴더 구조를 구축하기 위해 고안된 전문적인 프론트엔드 아키텍처 방법론이기 때문입니다 [21].
  • 이 개념을 통해 더 깊게 이해할 수 있는 부분: 폴더 간의 단방향 의존성 규칙과 각 폴더(Layer, Slice, Segment)가 담당해야 하는 역할의 엄격한 분리 방식 [22, 28].

• [[뇌와 팔다리의 분리 - 관심사의 분리 (Separation of Concerns)|Separation of Concerns]] (관심사의 분리)

  • 연결 이유: 폴더 구조를 설계하는 근본적인 목적이 UI 렌더링, 전역 상태 관리, 데이터 통신(API) 등의 책임을 각기 다른 위치로 분리하는 데 있기 때문입니다 [4, 29].
  • 이 개념을 통해 더 깊게 이해할 수 있는 부분: services/, store/, components/ 등의 폴더를 분리하여 단일 책임 원칙(SRP)을 프론트엔드 아키텍처 전반에 적용하는 방법 [4, 30].

• Naming Conventions (명명 규칙)

  • 연결 이유: 일관된 폴더 및 파일 명명 규칙(예: 폴더명은 kebab-case, 컴포넌트는 PascalCase)은 폴더 구조 내에서 파일을 예측 가능하게 찾고 충돌을 방지하는 핵심 규칙이기 때문입니다 [31-33].
  • 이 개념을 통해 더 깊게 이해할 수 있는 부분: 다양한 운영체제와 CI/CD 파이프라인에서 빌드 에러를 방지하고 팀 내 코드 가독성을 유지하는 방법 [34, 35].

Deeper Research Questions

• 기능 기반(Feature-based) 폴더 구조에서 각 기능이 상호작용해야 할 때 발생하는 교차 관심사(Cross-cutting concerns)나 공유 의존성을 어떻게 관리하고 해결할 수 있는가?
• 레거시 파일 유형 기반(File-type based) React 프로젝트를 기능 기반 혹은 Feature-Sliced Design으로 점진적으로 마이그레이션하기 위한 가장 안전하고 효율적인 단계는 무엇인가?
• Feature-Sliced Design의 단방향 의존성 원칙을 ESLint와 같은 정적 분석 도구로 자동 강제화(Governance)하는 방법은 무엇인가?
• 폴더 구조를 모듈화할 때 발생하는 파일 중첩 문제와 이를 피하기 위한 적절한 인덱스(Barrel) 파일 사용 전략의 장단점은 무엇인가?
• 상태 관리 라이브러리(Context API, Zustand, Redux 등)의 종류에 따라 권장되는 store/ 폴더 내부의 구조는 어떻게 달라져야 하는가?

Practical Application Contexts

• Implementation: React 컴포넌트를 생성할 때, 모든 요소를 components/ 폴더에 넣지 않고 특정 도메인(예: 인증)에만 쓰이는 요소는 features/auth/components/로 격리하여 캡슐화를 실천합니다.
• System Design: 프로젝트 초기 세팅 단계에서 비즈니스 도메인을 분석하여 어떤 코드가 전역(shared/ 또는 components/)에 속하고 어떤 코드가 로컬(features/)에 속할지 기준을 마련합니다.
• Operation / Maintenance: 기능에 버그가 발생했을 때, 해당 기능의 폴더(features/feature-name/)만 확인하면 UI, 상태, API 요청 로직이 모여 있어 디버깅 및 유지보수 속도가 크게 향상됩니다.
• Learning Path: 처음에는 단순한 플랫 구조로 React를 학습한 후, 컴포넌트가 30개 이상으로 늘어나는 시점에 기능 기반 폴더 구조를 도입하여 아키텍처 설계 역량을 기를 수 있습니다.
• My Project Relevance: 현재 진행 중이거나 리팩토링해야 할 React 코드베이스에서, 거대해진 components/ 폴더를 도메인 단위의 features/ 폴더로 나누고 재사용 불가 로직들을 분리하는 데 직접적으로 적용됩니다.

Adjacent Topics

• 상태 관리(State Management)
  • 확장 방향: 전역 상태(Global State)와 로컬 상태(Local State)를 어디에 보관해야 하는지, Zustand와 같은 도구가 store/ 폴더의 구조를 어떻게 단순화하는지 확장하여 조사할 수 있습니다.
• Code Splitting (코드 스플리팅)
  • 확장 방향: 라우트 혹은 폴더(Feature) 단위로 코드 스플리팅과 지연 로딩(Lazy Loading)을 적용하여 초기 번들 크기를 줄이고 성능을 최적화하는 전략과 연결됩니다.

---

Last updated: 2026-04-30