🏗️ React 프로젝트 구조, 어떻게 설계할까?

리액트 프로젝트를 처음 시작할 때 디렉토리 구조를 어떻게 짜야 할지 막막할 수 있다.
프로젝트가 커질수록 구조가 엉키기 쉬운데, 초반에 잘 정리해두면 유지보수와 협업이 훨씬 수월해진다.

오늘은 일반적인 React 앱 구조를 기준으로 각 디렉토리의 역할을 작성해본다.

---

1. 기본 구조 예시

my-react-app/
├── public/
├── src/
│   ├── assets/
│   ├── components/
│   ├── pages/
│   ├── hooks/
│   ├── utils/
│   ├── store/
│   ├── routes/
│   ├── App.tsx
│   └── main.tsx
├── .gitignore
├── index.html
├── package.json
└── tsconfig.json

---

2. 디렉토리별 설명

📁 public/

• 정적 파일을 보관하는 곳
• index.html이 이 폴더 안에 있음

📁 src/

프로젝트의 핵심 코드들이 들어있는 폴더

📁 assets/

• 이미지, 폰트, 공통 CSS 등 정적 리소스를 관리

📁 components/

• 여러 곳에서 재사용되는 컴포넌트들을 보관
• ex) Button, Modal, Header 등

📁 pages/

• 페이지 단위의 컴포넌트들
• React Router의 route와 1:1로 대응되는 경우가 많음

📁 hooks/

• 커스텀 훅을 정의
• ex) useInput, useDebounce, useAuth

📁 utils/

• 유틸 함수 모음 (ex. 날짜 포맷, 숫자 포맷, API 에러 처리 등)

📁 store/

• Redux 또는 Zustand 등 상태관리 로직을 분리
• 모듈화된 상태 slice들을 관리

📁 routes/

• 라우팅 정보 관리
• react-router-dom의 라우터 설정을 모아 관리

---

3. 확장 가능한 구조를 위한 팁

• 기능별로 폴더를 분리하는 방식도 있다 (Feature-based)

• 규모가 커지면 features/, services/, api/ 폴더 등도 고려

• 폴더 안에서도 index.ts를 활용하면 import 경로를 줄일 수 있다

  // 예: components/index.ts
  export { default as Button } from './Button';
  export { default as Header } from './Header';
  
  // 사용
  import { Button, Header } from '@/components';

---

4. 실제 Vite + TypeScript 환경과 연결하면?

src/
├── api/             # 서버 요청 모듈
├── components/
├── constants/       # 상수 정의
├── hooks/
├── pages/
├── routes/
├── store/           # Zustand or Redux
├── styles/          # 전역 스타일
├── types/           # 타입 정의 파일
├── utils/
├── App.tsx
└── main.tsx

---

5. 구조를 유지하는 습관

• 기능 단위로 분리하기
• 관심사 분리를 지키기 (UI vs Logic vs State)
• 네이밍을 일관되게
• 폴더가 너무 많아지는 것도 지양하기

---

🔨 TIL

• React 프로젝트 구조는 팀원과의 협업을 고려해 미리 설계하는 것이 중요하다.
• 기본적으로 components, pages, hooks, store, utils 등으로 나누고,
  규모가 커지면 기능 중심(feature-based) 구조로 전환할 수 있다.
• 폴더별 역할을 명확히 하고, index 파일을 적극적으로 활용하면 관리가 쉬워진다.