· haewonwon

Feature-Sliced Design(FSD)란?

기존 폴더 구조를 선택한 이유와 FSD의 필요성

현재 우리 프로젝트는 다음과 같은 폴더 구조를 사용하고 있습니다.

src/
 ├── assets
 ├── components
 ├── constants
 ├── contexts
 ├── hooks
 ├── layouts
 ├── pages
 ├── routes
 ├── services
 ├── stores
 ├── styles
 └── utils

이 구조는 많은 React 프로젝트에서 사용되는 전통적인 형태이며, 우리 팀 또한 “페이지 단위로 설계하고 개발하기 쉽게 만들기 위해서” 이 구조를 채택했습니다.

페이지 단위 개발 방식은 다음과 같은 장점이 있습니다.

  • 각 페이지가 하나의 독립된 단위로 보이므로 진입 장벽이 낮습니다.
  • 간단한 화면에서는 코드 위치를 빠르게 찾을 수 있습니다.
  • 초기 개발 속도가 빠릅니다.

하지만 프로젝트가 커지면서 다음과 같은 한계가 발생하기 시작했습니다.

페이지 단위 구조의 한계

1) 기능이 페이지 기준이 아니라 “곳곳에 흩어지는 문제”

페이지 단위 구조는 “한 페이지에서 필요한 파일이 여러 폴더에 흩어지는” 구조적 특성을 가집니다. 예를 들어 가게 찜하기 기능 하나를 찾으려면 다음처럼 폴더를 모두 돌아다녀야 합니다.

• components/
• hooks/
• services/
• stores/
• utils/

즉, 페이지 중심으로는 “기능(Feature)의 경계”를 명확히 설명할 수 없습니다. 페이지는 화면 단위이지 기능 단위가 아니기 때문입니다.

이로 인해 기능 수정 시 매번 여러 곳을 탐색해야 하고, 코드 탐색 비용이 커집니다.

2) 페이지에서 기능이 계속 쌓이며, 페이지 파일이 비대해짐

초기에는 페이지 내부의 UI, 상태, 로직이 모두 함께 있어도 문제가 없지만, 기능이 늘어나면 페이지 파일이 자연스럽게 다음과 같은 형태가 됩니다.

  • API 호출
  • 데이터 파싱
  • 비즈니스 로직
  • UI 렌더링
  • 전역 상태 연동
  • 사이드 이펙트 처리

즉, 페이지는 “혼합 영역”이 되어버리고 유지보수가 어려워집니다.

3) 기술별 폴더 구조는 프로젝트 커질수록 예측 가능성이 떨어짐

components/ 안에는 “재사용 UI”뿐 아니라 특정 페이지가 단독으로 쓰는 UI 컴포넌트까지 섞이게 됩니다.

hooks/, services/, utils/ 역시 프로젝트가 커질수록 역할이 흐려져 폴더 자체가 ‘모든 기능의 혼합 공간’으로 변하게 됩니다.

이로 인해 다음 문제들이 생깁니다.

  • 파일 위치 찾기 어려움
  • 기능별 관련 파일이 전혀 모여 있지 않음
  • 팀원 간 규칙 불일치로 구조가 점점 혼탁해짐

이러한 문제는 프로젝트 규모가 커질수록 더 심해집니다.

Feature-Sliced Design(FSD)가 필요한 이유

Feature-Sliced Design은 기존의 페이지 중심 구조가 갖는 단점을 해결하기 위해 “기능 단위로 코드를 구성하는 방식”을 제안합니다.

핵심 철학은 다음과 같습니다.

“기능은 페이지보다 고정적이며, 기능 단위로 코드가 모여 있을 때 유지보수성이 극대화됩니다.”

즉,

  • 페이지는 URL 라우팅이라는 UI 단위입니다.
  • 기능은 애플리케이션의 실제 비즈니스 단위입니다.

UI(페이지)는 시간이 지나면 변경되지만, 비즈니스 기능은 오랜 기간 유지되고 확장되기 때문에 기능 중심 구조(FSD)가 더 안정적입니다.

페이지 단위 개발과 FSD는 서로 대체 관계가 아닙니다

중요한 점은, FSD는 페이지 단위 개발을 부정하는 것이 아니라 “보완”하는 구조라는 점입니다.

FSD에서도 pages/ 레이어는 그대로 존재하며, URL 단위의 진입점 역할을 담당합니다.

단지 차이가 있다면:

  • pages/는 “UI 구성”을 하는 레이어
  • features/, entities/가 “기능과 도메인을 담당하는 레이어”

로 나누어져 기능 중심 사고를 강화한다는 점입니다.

FSD 적용 후 폴더 구조는 어떻게 바뀌는가

src/
 ├── app/          # 라우팅, 글로벌 설정, 전역 Provider 구성
 ├── processes/    # 인증, 온보딩 등 여러 기능이 결합된 플로우
 ├── pages/        # URL 단위 페이지(Next.js는 app/가 해당)
 ├── widgets/      # 화면의 큰 섹션 단위 UI(여러 feature/entity 조합)
 ├── features/     # 로그인, 찜하기, 검색 등 단일 기능 단위
 ├── entities/     # User, Store, Review 등 도메인 단위 기능 집합
 └── shared/       # 공용 UI, hooks, libs, api, utils 등

정리

  • 우리는 초기 개발 편의성을 위해 페이지 중심 폴더 구조를 선택했습니다.
  • 하지만 기능이 증가하면서 코드가 여러 폴더로 흩어지며 유지보수 비용이 증가했습니다
  • Feature-Sliced Design은 이러한 문제를 해결하기 위해 페이지가 아닌 기능/도메인 중심으로 코드를 모으는 방식입니다.
  • FSD는 페이지 구조를 대체하는 것이 아니라, 페이지 바깥의 “기능 단위 구조”를 명확히 정의하여 프로젝트 확장성을 높이는 아키텍처입니다.

참고 자료: https://nettle-pilot-25c.notion.site/8-FSD-2b1178c4afac80e3a114c6358b89c37b