Antigravity Agent
4.7 KiB
4.7 KiB
React Project Setup
📌 Brief Summary
React Project Setup은 확장 가능하고 유지보수가 용이한 프론트엔드 애플리케이션을 구축하기 위해 프로젝트의 폴더 구조, 파일 명명 규칙, 그리고 빌드 도구를 구성하는 초기 단계입니다. 2025년 기준으로는 파일 유형 중심의 분리보다는 기능(Feature) 중심으로 코드를 조직하는 것이 권장되며, 일관된 명명 규칙과 Vite 같은 최신 빌드 도구를 활용하여 개발 효율성을 높입니다. 이를 통해 대규모 애플리케이션에서도 코드의 결합도를 낮추고 응집도를 높여 프로젝트가 복잡해지는 것을 방지할 수 있습니다.
📖 Core Content
-
최신 빌드 도구 및 환경 설정 (Vite 도입):
- 2025년 React 생태계에서는 기존의 Create React App(CRA)을 대신하여 Vite가 새로운 표준 빌드 도구로 자리 잡았습니다 [1].
- Vite는 개발 중에는 코드를 네이티브 ES 모듈 형태로 브라우저에 직접 제공하여 빠른 시작 및 핫 모듈 교체(HMR)를 지원하고, 배포 시에는 Rollup을 사용하여 최적화된 번들을 생성합니다 [2-5].
- 설정 파일(
vite.config.js)에서 기존 Babel 대신 Rust 기반의 SWC 컴파일러 플러그인(@vitejs/plugin-react-swc)을 사용하여 대규모 프로젝트의 빌드 속도를 크게 향상시킬 수 있으며, 깔끔한 파일 임포트를 위한 경로 별칭(Path Aliases) 설정도 구성할 수 있습니다 [6-8].
-
확장 가능한 폴더 구조 설계 (Folder Structure):
- 과거처럼 컴포넌트, 훅, 스타일 등 파일 유형별로 구조를 나누는 방식(Flat Structure 및 File-Type Based Structure)은 프로젝트 규모가 커질수록 확장에 불리하며 코드를 관리하기 어렵게 만듭니다 [9-11].
- 기능 기반 구조(Feature-Based Structure): 비즈니스 도메인이나 기능별로 관련 컴포넌트, 훅, 로직, 타입 등을 하나의 기능 폴더(예:
src/features/auth) 내에 캡슐화하는 구조가 널리 권장됩니다 [11-14]. - 하이브리드 방식: 재사용 가능한 범용 UI 컴포넌트(
components/), 전역 상태 관리(store/또는context/), 외부 통신 로직(services/), 공통 유틸리티(utils/) 등은 기능 폴더 외부에 배치하고, 특정 기능에 종속된 코드는features/아래에 두는 방식이 실무에서 가장 균형 잡힌 구조로 평가받습니다 [14-22]. - Feature-Sliced Design (FSD): 더 엄격한 아키텍처가 필요한 경우, 시스템을 공유(shared), 엔티티(entities), 기능(features), 위젯(widgets), 페이지(pages), 앱(app) 등의 계층으로 나누어 상위 계층이 하위 계층에만 의존하도록 단방향 의존성을 강제합니다 [13, 23-25].
-
일관된 명명 규칙 (Naming Conventions):
- 파일 및 폴더명: OS 환경(Windows/macOS는 대소문자 구분 안 함, Linux는 구분) 간의 차이로 인한 CI/CD 빌드 오류를 막기 위해, 파일과 폴더 이름은
kebab-case를 사용하는 것이 안전하고 가독성이 높습니다 (예:user-profile.tsx) [26-29]. - 컴포넌트 및 타입/인터페이스: React 컴포넌트 이름과 TypeScript 타입은 일반 함수나 HTML 요소와 명확히 구분되도록
PascalCase를 사용합니다 [26, 28-31]. - 함수, 변수, Props:
camelCase를 사용합니다. 특히 boolean 상태 변수는is,has,should등의 접두사를 사용하고, 이벤트 핸들러에는handle이나on을, 커스텀 훅에는use접두사를 붙여 의도를 명확히 합니다 [26, 28, 30, 32]. - 상수(Constants): 상수는
UPPER_SNAKE_CASE로 작성하여 식별성을 높입니다 [26, 33].
- 파일 및 폴더명: OS 환경(Windows/macOS는 대소문자 구분 안 함, Linux는 구분) 간의 차이로 인한 CI/CD 빌드 오류를 막기 위해, 파일과 폴더 이름은
🔗 Knowledge Connections
- Related Topics: Frontend Folder Structure, Feature-Sliced Design, Clean Code Principles, Vite Build Tool
- Projects/Contexts: 대규모 React 애플리케이션 아키텍처 구성, 2025 프론트엔드 엔지니어링 표준 확립, 프론트엔드 리팩토링 및 코드 유지보수
- Contradictions/Notes: 도메인 및 기능별(Feature-Based) 폴더 분리는 대규모 앱의 확장에 매우 유리하지만, 규모가 매우 작은 소형 프로젝트의 경우 기능 기반의 중첩된 폴더 구조를 도입하는 것이 오히려 불필요한 오버헤드와 복잡성을 초래할 수 있다는 점이 지적됩니다 [34]. 또한, React 컴포넌트 내부의 함수명은
PascalCase를 강제하지만 이를 담고 있는 물리적 파일명은kebab-case를 사용하는 것을 권장하므로 두 규칙 사이의 일관된 매핑 관리가 중요합니다 [28].
Last updated: 2026-04-26