React 폴더 구조 완전 가이드: 유지보수성과 확장성을 높이는 설계 전략

🏗 React 앱 유지보수성과 확장성을 위한 폴더 구조 & 아키텍처 설계 가이드

React 프로젝트가 커지면 가장 먼저 고민되는 것 중 하나가 “구조”입니다.

초기에는 컴포넌트 몇 개로 충분하지만, 규모가 커지면 다음과 같은 문제가 생깁니다:

• 컴포넌트가 무한히 커지거나 중복됨
• 파일이 뒤섞여서 어디에 뭘 넣어야 할지 모름
• 유지보수가 어려워지고 새로운 기능 추가도 부담스러워짐

이런 문제를 해결하려면 처음부터 유지보수성과 확장성을 고려한 구조 설계가 필요합니다.

이 글에서는 실제 프로젝트에서 활용되는 구조들을 소개하고,
각 패턴의 장단점과 선택 기준, 실전 예제까지 정리해볼게요.

🎯 폴더 구조 설계의 핵심 목표

• 기능 단위로 명확하게 분리
• 역할이 분명한 디렉토리와 파일명
• 작은 컴포넌트도 구조화 가능해야 함
• 테스트, 스타일, 상태 등 연관 파일을 묶어 관리

🧱 1. 가장 많이 쓰는 기본 구조: 기능 기반 구조 (Feature-based)

✅ 예시 구조

src/
├── features/
│   ├── auth/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   └── AuthPage.jsx
│   ├── products/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   └── ProductList.jsx
├── shared/
│   ├── components/
│   ├── hooks/
│   ├── utils/
│   └── constants/
├── routes/
├── App.jsx
└── index.jsx

📌 장점

• 각 기능 단위로 파일이 정리되어 유지보수가 쉬움
• 도메인 주도 설계(DDD)와도 잘 어울림
• 협업 시 작업 분담이 자연스러움

📌 단점

• 너무 작은 기능도 디렉토리로 나누면 과도한 트리
• 컴포넌트간 공통 로직이 분산될 수 있음

🧩 2. Atomic Design 구조

디자인 시스템 기반 UI 프로젝트에서 효과적인 구조입니다.

✅ 계층 예시

• Atoms: 버튼, 인풋, 라벨 등 가장 작은 요소
• Molecules: Atom을 조합한 단위 (예: 검색바)
• Organisms: 더 큰 조합 단위 (예: 헤더, 카드)
• Templates: 페이지를 구성하는 뼈대
• Pages: 실제 라우팅되는 최종 페이지

src/
├── components/
│   ├── atoms/
│   ├── molecules/
│   ├── organisms/
│   ├── templates/
│   └── pages/

📌 장점

• 재사용 가능한 UI 설계에 강력함
• 디자이너와 협업이 수월해짐
• 디자인 시스템 구축에 최적화

📌 단점

• 기능 중심이 아니라 역할 중심이라 비즈니스 로직 분리가 필요

🧠 3. Hybrid 구조 (추천)

현업에서 가장 많이 쓰이는 구조입니다.
기능 중심으로 설계하면서 공통 UI는 Atomic 구조로 정리합니다.

src/
├── features/
│   ├── cart/
│   │   ├── CartPage.jsx
│   │   ├── CartService.js
│   │   └── cartSlice.js
│   ├── user/
│   │   ├── UserProfile.jsx
│   │   └── useUserData.js
├── components/
│   ├── atoms/
│   ├── molecules/
│   ├── organisms/
├── shared/
│   ├── hooks/
│   ├── utils/
│   └── constants.js
├── store/
│   └── index.js
├── routes/
└── App.jsx

📌 장점

• 기능 중심 + UI 재사용 구조
• 프로젝트가 커져도 유연하게 대응 가능

🧪 상태 관리 구조 설계 예시

• Redux:

  store/
  ├── index.js
  └── slices/
      └── userSlice.js

• Zustand:

  features/user/
  └── useUserStore.js

• Context:

  contexts/
  ├── ThemeContext.jsx
  └── AuthContext.jsx

🛠 폴더 구조 설계 팁

1. 기능 단위 기준으로 폴더를 분리하세요
2. 공통 컴포넌트는 'shared' 또는 'components'로 따로 모으기
3. 컴포넌트, 상태, 스타일 파일을 한 기능 안에 묶자

features/user/
├── UserProfile.jsx
├── useUserData.js
├── userService.js
├── userSlice.js
├── User.module.css

4. 라우팅은 명확히 분리해서 관리
5. 네이밍 규칙은 팀 내 표준을 정하자

✨ 실전에서 고려할 구조 선택 기준

기준	추천 구조
단순한 프로젝트	기능 기반 (features/)
디자인 시스템 강한 앱	Atomic Design
확장성, 유지보수 고려	Hybrid 구조
팀 협업이 많은 경우	폴더 정리 기준 명확 + 역할 구분 구조
SSR/Next.js 기반 앱	pages 중심 구조 + 기능 모듈화 병행

✅ 마무리 요약

React 프로젝트의 폴더 구조는 단순한 파일 정리가 아니라
유지보수, 협업, 확장성에 직접적인 영향을 주는 설계 전략입니다.

구조를 설계할 때 항상 질문하세요:

• 새로운 기능을 추가할 때 어디에 둘까?
• 이 컴포넌트, 나중에도 재사용 가능할까?
• 지금 구조가 6개월 뒤에도 이해가 될까?

🔑 핵심 체크리스트

• 기능 단위로 폴더를 분리하자
• 상태, 컴포넌트, 스타일 파일을 함께 묶자
• UI는 재사용 가능하게 계층 구조로
• 상태 관리에 따라 store 구조 설계도 함께 고려
• 너무 세분화하지 말고, “실용성 중심”으로