[React] 📁 프로젝트 폴더 구조, 어떻게 구성해야 할까?

🧭 들어가며

React 프로젝트가 점점 커지면 파일과 컴포넌트가 어지럽게 섞여 유지보수가 어려워집니다.
“기능별로 나눌까?”, “컴포넌트는 어디에 두지?”, “hooks, utils는 또 어디에?”

이 글에서는 실무와 사이드 프로젝트 모두에 적용할 수 있는 깔끔한 폴더 구조 예시와 이유를 공유합니다.

 

※ 실무 경험은 없지만 현업에 계신 선배들의 조언과 제가 프로젝트를 하면서 경험한 것들과

서치 등을 활용하여 종합적으로 정리한 내용이므로 주관적인 견해가 들어간 점 양해주셔서 참고 정도로만

해주시고 본인들의 상황에 맞게 정하시면 좋을 것 같습니다.

 

 

 

---

🧱 기본 구조 예시

src/
├── assets/          # 이미지, 폰트, 정적 파일
├── components/      # 재사용 가능한 UI 컴포넌트
├── features/        # 페이지 or 도메인 단위 기능 모음
│   └── user/
│       ├── api.ts   # 해당 도메인의 API
│       ├── UserPage.tsx
│       └── userSlice.ts (zustand/redux)
├── hooks/           # 커스텀 훅
├── pages/           # 라우팅 페이지 (React Router or Next.js에서 사용)
├── routes/          # 라우팅 정의 (React Router용)
├── stores/          # zustand/redux 등 상태 관리
├── styles/          # 전역 스타일 (emotion/styled-components/global.css 등)
├── utils/           # 유틸 함수 모음
├── types/           # 타입 정의 파일들 (공용 interface 등)
└── main.tsx         # 앱 진입점

 

 

---

🧩 폴더별 설명

1️⃣ components/

• 재사용 가능한 작은 UI 단위를 담는 곳
• 예: Button, Modal, Card 등
• 일반적으로 기능과 무관한 presentational components를 모아둡니다.

components/
├── Button.tsx
├── Modal.tsx
└── LoadingSpinner.tsx

 

2️⃣ features/

• 실제 비즈니스 도메인 단위로 나누는 구조 (예: user, post, chat 등)
• 각 도메인별로 해당 API, 상태, 컴포넌트를 함께 관리

features/
└── post/
    ├── PostPage.tsx
    ├── PostList.tsx
    ├── api.ts
    └── postStore.ts

이 구조를 **"기능 기반(feature-based) 구조"**라고 합니다.
규모가 커질수록 유지보수가 쉬워지고, 협업할 때 영역이 명확해집니다.

 

3️⃣ hooks/

• 재사용 가능한 로직을 커스텀 훅으로 분리
• 예: useDebounce, useFetch, useModal

hooks/
├── useDebounce.ts
└── useLocalStorage.ts

 

4️⃣ stores/

• 전역 상태 관리 (Zustand, Redux 등)
• features 안에 도메인별로 store를 둘 수도 있고, 여기에 전역으로 두어도 OK

 

5️⃣ routes/

• React Router를 사용할 경우 라우팅 정의를 여기에 따로 분리
• 유지보수와 가독성 모두 향상

// routes/index.tsx
import { Routes, Route } from 'react-router-dom';
import HomePage from '@/pages/HomePage';
import UserPage from '@/features/user/UserPage';

export default function AppRoutes() {
  return (
    <Routes>
      <Route path="/" element={<HomePage />} />
      <Route path="/user" element={<UserPage />} />
    </Routes>
  );
}

 

6️⃣ types/

• 프로젝트 전반에서 공통으로 쓰이는 타입, 인터페이스 정의
• 예: User, Post, ApiResponse 등

 

7️⃣ utils/

• 비즈니스 로직과 분리된 유틸 함수들
• 날짜 포맷팅, 숫자 단위 변환, validation 등

export const formatDate = (date: string) => { ... };

 

 

 

---

⚖️ 구조 설계 시 고려할 점

✅ 컴포넌트와 도메인은 분리하자
공통 UI 요소는 components/, 특정 기능에 종속된 컴포넌트는 features/로

 

✅ hooks, utils는 기능과 분리하자
어디서든 재사용 가능한 로직은 별도 디렉터리로 분리하는 게 유지보수에 용이

 

✅ 페이지와 라우트 구분
pages/는 실제 JSX 컴포넌트만 두고, routes/에서 라우팅을 모아서 관리하면 깔끔합니다.

 

✅ 상태는 도메인과 함께 또는 전역 구분
작은 프로젝트면 stores/에 모아도 좋고, 커지면 features/도메인/store.ts로 분리

 

 

---

🏁 마무리

폴더 구조에 정답은 없지만,
도메인 기준으로 나누고 재사용 가능한 요소는 공통으로 분리하면
협업에서도, 리팩터링할 때도 매우 유리합니다.

“작은 앱처럼 보이던 프로젝트도, 어느새 100개 넘는 파일이 생깁니다.”

 

지금부터라도 폴더 구조를 체계적으로 관리해보세요!
지금 구조가 답답하거나 지저분하다면, 이 구조를 참고해서 리팩토링해보는 것도 추천합니다.