FSD(FEATURE-SLICED DESIGN) 폴더 구조 완전 정복

🤔 "우리 프로젝트 폴더 구조, 이게 최선일까?"

프론트엔드 개발을 하다 보면 프로젝트가 커질수록 파일이 난잡해지고 유지보수가 어려워지는 경험을 해봤을 것이다.

 

컴포넌트는 어디에 둬야 할까?
비즈니스 로직은 어디에 배치해야 할까?
API 호출 로직은 어디에 둬야 하지?
페이지가 많아질수록 관리가 점점 힘들어지는데...

이 고민을 해결해 줄 폴더 구조가 바로 FSD(Feature-Sliced Design) 이다.

---

🔥 FSD(Feature-Sliced Design)란?

FSD는 기능(Feature) 중심으로 코드를 분리하는 방식으로, 러시아 개발자 커뮤니티에서 처음 정립된 폴더 구조이다.
기존의 페이지(Page)-컴포넌트(Component)-서비스(Service) 방식과 달리, 기능 단위로 프로젝트를 나눠서 유지보수를 쉽게 만든다고 한다.

 

📂 FSD 폴더 구조 한눈에 보기

📂 src
 ┣ 📂 app       # 애플리케이션 레벨 설정 (라우팅, 글로벌 설정 등)
 ┣ 📂 shared    # 프로젝트 전역에서 공유되는 UI 컴포넌트, 유틸 함수, hooks 등
 ┣ 📂 entities  # 핵심 도메인 모델과 관련된 상태 관리, API 정의
 ┣ 📂 features  # 개별적인 기능 단위 (로그인, 검색, 장바구니 등)
 ┣ 📂 widgets   # 여러 개의 feature를 조합한 UI 블록 (헤더, 사이드바, 대시보드 등)
 ┣ 📂 pages     # 페이지 단위의 구성 요소 (ex. 로그인 페이지, 프로필 페이지)
 ┗ 📂 processes # 여러 페이지와 기능을 결합하는 비즈니스 흐름 단위

---

🧐 FSD 폴더 구조 상세 분석

1️⃣ app/ → 애플리케이션 초기 설정

• index.tsx 또는 App.tsx 위치
• 라우팅, 테마, 전역 상태 설정 등 포함

📌 예시

app/
 ┣ providers/       # 상태 관리, 테마 제공
 ┣ routes/          # 라우팅 설정
 ┗ App.tsx         # 애플리케이션 진입점

---

2️⃣ shared/ → 모든 곳에서 재사용 가능한 요소

• 공통 UI 컴포넌트 (버튼, 인풋, 모달 등)
• 유틸리티 함수, hooks, 스타일 파일

📌 예시

shared/
 ┣ ui/          # 버튼, 입력 필드 등 공통 UI
 ┣ api/         # HTTP 요청 함수
 ┣ hooks/       # 커스텀 훅
 ┣ lib/         # 헬퍼 함수, 포맷터 등
 ┗ styles/      # 전역 스타일

---

3️⃣ entities/ → 도메인 모델과 관련된 코드

• API 호출, 상태 관리, 타입 정의 등
• 예를 들어 User, Product 등의 엔터티 관리

📌 예시

entities/
 ┣ user/       # 사용자 관련 API, 상태 관리
 ┣ product/    # 상품 관련 데이터 처리
 ┗ cart/       # 장바구니 데이터 관리

---

4️⃣ features/ → 독립적인 기능 단위

• 로그인, 회원가입, 검색, 장바구니 등
• 여러 페이지에서 재사용 가능

📌 예시

features/
 ┣ auth/       # 로그인, 회원가입
 ┣ search/     # 검색 기능
 ┣ cart/       # 장바구니 기능
 ┗ profile/    # 프로필 수정 기능

---

5️⃣ widgets/ → UI 블록 조합 (헤더, 사이드바 등)

• 여러 feature를 조합하여 UI를 구성
• 페이지와 독립적으로 사용 가능

📌 예시

widgets/
 ┣ navbar/     # 내비게이션 바
 ┣ sidebar/    # 사이드바
 ┣ dashboard/  # 대시보드
 ┗ footer/     # 푸터

---

6️⃣ pages/ → 라우트 단위의 페이지

• 각각의 페이지는 feature와 widget을 조합하여 구성

📌 예시

pages/
 ┣ home/       # 홈 페이지
 ┣ login/      # 로그인 페이지
 ┣ profile/    # 프로필 페이지
 ┗ dashboard/  # 대시보드

---

7️⃣ processes/ → 비즈니스 흐름 관리

• 여러 페이지, 위젯, 기능을 하나로 묶어 흐름을 정의

📌 예시

processes/
 ┣ checkout/   # 결제 프로세스 (장바구니 → 결제 → 완료)
 ┣ onboarding/ # 신규 사용자 온보딩 플로우
 ┗ auth-flow/  # 로그인 → 권한 체크 → 대시보드

---

🎯 FSD 구조의 장점

✅ 유지보수 용이 → 기능별로 분리되어 있어 수정하기 쉬움
✅ 확장성 → 새로운 기능을 추가할 때 기존 코드에 영향을 최소화
✅ 재사용성 증가 → shared/, widgets/ 폴더 덕분에 중복 코드 감소
✅ 도메인 중심 설계 → 비즈니스 로직과 UI가 적절히 분리됨

---

🚀 FSD, 적용해 볼까?

🔥 여러분의 프로젝트에서는 어떤 폴더 구조를 사용하고 있나요?
처음에는 익숙하지 않을 수 있지만, 프로젝트 규모가 커질수록 진가를 발휘하는 구조인 것 같다. 특히 프론트엔드 아키텍처에 대한 고민이 많다면 한 번 적용해보는 것도 추천한다!