React 폴더 구조 & 아키텍처 설계 가이드 – 유지보수성과 확장성을 높이는 실전 전략
React 앱 유지보수성과 확장성을 위한 폴더 구조 & 아키텍처 설계 가이드 – 기능 중심 vs 도메인 중심 비교와 실전 설계법
React 프로젝트가 커지면서 가장 먼저 복잡해지는 건 코드보다도 폴더 구조입니다.
처음엔 components 폴더 하나로 시작하지만, 점점 hooks, pages, utils, store 등 이름이 늘어나고, 나중엔 어느 파일이 어디에 있어야 할지 헷갈리기 시작하죠.
이번 글에서는 기능 중심 vs 도메인 중심 폴더 구조 비교부터, Atomic Design + Feature-based 구조 조합까지 실무에 강한 React 아키텍처 설계 전략을 3단계에 걸쳐 정리합니다.
1. 📁 기본 구조의 진화 과정
프로젝트가 커질수록 폴더 구조는 다음과 같은 단계로 진화합니다:
- 기초 구조: src 안에 모든 것을 몰아넣는 형태
- 역할 분리 구조: 컴포넌트, 훅, 유틸 등 역할별 디렉터리 분리
- 기능 중심 구조: 페이지나 도메인 단위로 디렉터리 구성
- 멀티 도메인 구조: 대규모 프로젝트에 맞는 도메인+레이어 혼합 방식
✅ 예: 기초 구조
src/
├── components/
├── pages/
├── App.js
└── index.js❌ 문제점
- 같은 기능이라도 서로 다른 폴더에 나뉘어 있음
- 확장성, 테스트, 유지보수 모두 어려워짐
2. 🧱 역할 기반 구조 vs 기능 기반 구조 비교
📌 역할 기반 구조 (Role-based)
src/
├── components/
├── hooks/
├── utils/
├── services/
├── store/
✅ 장점
- 처음 배우기 쉽고 직관적
- 비슷한 역할끼리 묶여 있어 명확함
❌ 단점
- 한 기능에 관련된 파일이 여기저기 흩어짐
- 기능 단위 테스트 및 유지보수가 어려움
📌 기능 기반 구조 (Feature-based)
src/
├── features/
│ ├── auth/
│ │ ├── components/
│ │ ├── hooks/
│ │ └── store.js
│ ├── product/
│ │ ├── components/
│ │ └── productSlice.js
✅ 장점
- 한 기능에 필요한 모든 코드가 한 곳에
- 도메인 단위 유지보수가 쉬움
- 기능별 모듈화 → 팀 단위 작업에 유리
❌ 단점
- 파일이 중복되어 보일 수 있음
- 초기 학습이 약간 까다로움
3. 🗂️ 실전 Feature 중심 폴더 구조 예시
기능 중심 구조는 대규모 프로젝트일수록 효과를 발휘합니다.
📁 구조 예시 (중대형 기준)
src/
├── app/ # 앱 설정 (라우팅, 스토어, 글로벌 스타일 등)
├── features/
│ ├── auth/
│ │ ├── components/
│ │ ├── hooks/
│ │ ├── pages/
│ │ ├── api/
│ │ └── store.js
│ ├── product/
│ │ ├── components/
│ │ ├── hooks/
│ │ └── productSlice.js
├── shared/ # 공통 컴포넌트, 훅, 유틸 등
│ ├── components/
│ ├── hooks/
│ ├── constants/
├── styles/ # 글로벌 스타일
├── assets/ # 이미지, 폰트 등 정적 자원
├── index.tsx
└── App.tsx각 feature 안에 필요한 모든 요소가 함께 구성되어 있어 **코드 이동 없이도 한 기능을 온전히 파악하고 유지보수**할 수 있어요.
4. 🧩 레이아웃 중심 구조 분리 전략
프로젝트가 커지면 페이지별 레이아웃도 달라집니다.
예시:
- 메인 레이아웃 (헤더/푸터 포함)
- 관리자 대시보드 레이아웃 (사이드바 포함)
- 로그인/회원가입 레이아웃 (심플)
📦 구조 예시
src/
├── layouts/
│ ├── MainLayout.tsx
│ ├── AdminLayout.tsx
│ └── AuthLayout.tsx📌 페이지와 조합 예시
// pages/Home.tsx
import MainLayout from '@/layouts/MainLayout';
export default function Home() {
return (
<MainLayout>
<HeroSection />
<ProductGrid />
</MainLayout>
);
}➡️ 이렇게 하면 레이아웃 재사용 + UX 통일성 + 유지보수 세 마리 토끼를 잡을 수 있어요.
5. 🧱 Atomic Design과 기능 중심 구조의 하이브리드
요즘은 Atomic Design을 Feature 구조에 결합하는 방식이 가장 실용적입니다.
예시: features 내 UI 분할
features/
└── product/
├── atoms/
│ └── ProductImage.tsx
├── molecules/
│ └── ProductCard.tsx
├── organisms/
│ └── ProductGrid.tsx
├── pages/
└── store.ts➡️ 디자인 시스템을 코드 구조에 반영하면서도, 도메인 단위로 관리할 수 있습니다.
6. 🧩 컴포넌트 분리 기준 – 언제 쪼개고, 어디에 둘 것인가?
“컴포넌트를 어떻게 나누면 좋을까?”는 React 개발에서 가장 자주 나오는 질문입니다.
✅ 분리 기준 5가지
- 재사용 가능성: 다른 화면에서도 쓸 수 있는가?
- 의미 단위 완결성: UI 구조가 명확한 하나의 역할인가?
- 상태 보유 여부: 상태가 있다면 위쪽으로 끌어올릴 여지가 있는가?
- 길이: 한 파일 100줄 이상이면 분리 고려
- 테스트 가능성: 테스트 단위로 나누기 적절한가?
📌 위치 결정 가이드
- features 내부: 도메인 종속 컴포넌트 (예: ProductCard)
- shared/components: 재사용 가능한 범용 컴포넌트 (예: Button, Modal)
7. ✅ 테스트, 스토리북, 타입 설계까지 구조에 포함하자
📦 테스트 파일 위치 예시
ProductCard/
├── index.tsx
├── ProductCard.test.tsx
└── ProductCard.stories.tsx📌 통합 디렉터리 패턴
- 컴포넌트 코드, 테스트, 스토리북, 스타일을 한 디렉터리에 통합
✅ 장점
- 컴포넌트와 관련된 모든 것을 한눈에 관리
- 협업자와의 의사소통이 쉬움
8. 🧠 마무리 – 폴더 구조는 팀의 협업 전략이다
잘 짜인 폴더 구조는 단지 보기 좋기 위해서가 아니라, 팀의 협업 속도를 높이고, 유지보수 부담을 줄이는 중요한 전략입니다.
✨ 핵심 요약
- 기초 구조 → 역할 기반 → 기능 기반 → 레이아웃/도메인 결합 구조로 진화
- Atomic Design + Feature 구조 = 실용적 확장 구조
- shared / features / app 디렉터리 구분은 필수
- 테스트, 스토리북, 타입은 컴포넌트와 함께 위치
- 정답은 없지만, ‘예측 가능하고 일관된’ 구조가 가장 좋다
React 앱 구조를 잘 설계하면, 한 줄의 코드를 수정하는 시간이 10분에서 10초로 줄어듭니다.
이번 글이 여러분의 프로젝트 폴더 구조를 설계하는 데 실질적인 도움이 되었기를 바랍니다!
긴 글 읽어주셔서 감사합니다. 공감, 댓글, 공유로 응원해주시면 다음 글 제작에 큰 힘이 됩니다 🙌