Antigravity Agent
4.6 KiB
4.6 KiB
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