Antigravity Agent
3.9 KiB
3.9 KiB
📌 Brief Summary
React 폴더 구조는 애플리케이션의 디렉터리와 파일을 체계적으로 관리하여 유지보수성, 확장성, 협업 효율성을 높이기 위한 조직화 프레임워크다. 현대 React 생태계에서는 파일 유형 중심의 단순 분리를 넘어, 비즈니스 도메인과 기능을 중심으로 로직과 UI를 응집시키는 Feature-based 또는 Feature-Sliced Design (FSD) 구조가 권장된다.
📖 Core Content
- 일반적인 폴더 구조 접근 방식
- File-Type Based: 컴포넌트, 훅, 유틸리티 등 기술적 역할에 따라 분류 (소규모에 적합).
- Feature-Based: 인증, 대시보드 등 비즈니스 기능별로 폴더를 구성하여 캡슐화와 독립적 개발을 가능하게 함.
- 2025 권장 하이브리드 구조
assets/: 정적 자원 중앙 관리.components/: 전역 공유 공통 UI 컴포넌트.features/: 도메인 기반 기능 코드 (API, 고유 컴포넌트, 훅 포함).services/(또는api/): 외부 통신 로직 격리.store/또는context/: 전역 상태 관리 로직.
- Feature-Sliced Design (FSD) 아키텍처
- 책임과 범위에 따라
app,pages,widgets,features,entities,shared계층으로 분리. - 단방향 의존성과 Public API(
index.ts) 규칙을 통해 모듈 독립성을 극대화한다.
- 책임과 범위에 따라
- 네이밍 컨벤션과의 연계
- 컴포넌트는
PascalCase, 파일 및 폴더 이름은 운영체제 호환성을 위해kebab-case를 적용하는 것이 표준이다.
- 컴포넌트는
⚖️ Trade-offs & Caveats
- 구조적 복잡도: FSD와 같은 엄격한 아키텍처는 코드의 예측 가능성을 높이지만, 초기 설계 비용이 크고 파일 이동 시 인지적 부하가 발생할 수 있다.
- 공통 자원 비대화: 기능별로 나누다 보면
shared폴더가 쓰레기통처럼 비대해질 위험이 있으므로 정기적인 거버넌스가 필요하다. - 학습 곡선: 새로운 팀원이 복잡한 계층 구조를 이해하고 올바른 위치에 코드를 작성하기까지 온보딩 시간이 소요된다.
🔗 Knowledge Connections
Related Concepts (Auto-Linked)
- ESLint
- Feature-Sliced_Design
- Frontend
- Index
- Management
- Naming Conventions
- React
- Research
- Separation_of_Concerns
- State
Related Concepts
- Feature-Sliced Design (FSD): 대규모 시스템 구조화의 표준 (관계: 상위 아키텍처)
- Separation of Concerns: 폴더 분리의 근본적 철학 (관계: 설계 원리)
- Single Responsibility Principle (SRP): 파일 단위 모듈화의 기준 (관계: 개별 컴포넌트 설계 원칙)
Deeper Research Questions
- 프로젝트의 복잡도가 어느 임계점에 도달했을 때 File-type 기반에서 Feature-based 구조로 전환하는 것이 가장 비용 효율적인가?
- FSD 구조 내에서 복수의 'Features'가 데이터를 공유해야 할 때, 의존성 순환을 방지하기 위한 'Entities' 레이어 활용법은?
- Next.js의 App Router 파일 규약(
page.tsx,layout.tsx)과 커스텀 폴더 구조를 충돌 없이 통합하는 전략은? index.ts를 통한 캡슐화가 트리 쉐이킹(Tree Shaking) 성능에 미치는 구체적인 영향은 무엇인가?- 대규모 팀에서 린트 규칙(ESLint)을 통해 폴더 계층 간의 잘못된 참조를 자동으로 감지하고 차단하는 설정 방안은?
Practical Application Contexts
- 신규 대규모 프로젝트 셋업: 확장성을 고려한 FSD 기반 폴더 구조 설계 및 템플릿화.
- 레거시 구조 개선: 엉망으로 섞인
components폴더를 도메인 중심의features폴더로 점진적 재배치.
Adjacent Topics
- State Management Architectures
- Frontend Naming Conventions
- Micro-Frontends Project Structure