시스매

FSD

7 min read

2025-08-30 13:02

Tags: 리액트 넥스트

FSD (Featur-Sliced-Design)

1. 레이어

app → pages → widgets → features → entities → shared

  • 상위 레이어는 하위 레이어만 import 가능

  • 하위 레이어는 상위 레이어를 알 수 없음

  • app: 애플리케이션 초기화 및 전역 설정

    • Provider, Router, 전역 스타일, 전역 타입 선언
    • 애플리케이션 전반적으로 적용되는 기능들

  • pages: 라우팅 가능한 화면 정의

    • 애플리케이션의 각 페이지
    • URL과 매핑되는 최상위 컴포넌트들

  • widgets: 독립적인 UI 블록

    • 여러 feature를 조합한 의미 있는 블록
    • Header, Footer, Sidebar 등

  • features: 사용자 시나리오와 비즈니스 로직

    • 동사적 의미의 비즈니스 기능
    • 사용자에게 비즈니스 가치를 전달하는 행위

  • entities: 비즈니스 엔터티

    • User, Product, Order 등 핵심 비즈니스 객체
    • 데이터 모델과 관련 로직

  • shared: 재사용 가능한 공통 요소

    • UI 키트, 유틸리티 함수, API 클라이언트
    • 프로젝트 특정 로직에 종속되지 않는 기능들

2. 슬라이스

  • 비즈니스 중심 명명: user, post, comment, auth 등
  • 독립성 보장: 같은 레이어 내 슬라이스 간 import 금지
  • 높은 응집도: 관련 기능을 한곳에 모음

3. 세그먼트

  • 기술적 목적에 따라 코드를 그룹화
  • ui: UI 컴포넌트와 관련 요소들
    • React 컴포넌트, 스타일, 데이터 포맷팅 함수
  • model: 비즈니스 로직과 데이터 관리
    • 상태 관리, 액션, 셀렉터, 비즈니스 규칙
  • api: 외부 API와의 통신
    • 백엔드 API 메서드, 요청 함수, 데이터 타입
  • lib: 보조 및 인프라 코드
    • 헬퍼 함수, 유틸리티, 인프라 로직
  • config: 설정과 상수
    • 환경 변수, 설정 파일, 상수 정의
src/
├── app/
│   ├── providers/         # React Query, Redux 등
│   ├── styles/           # 전역 스타일
│   └── types/            # 전역 타입 정의
├── pages/
│   ├── home/
│   │   ├── ui/
│   │   │   └── HomePage.tsx
│   │   └── index.ts
│   └── dashboard/
│       ├── ui/
│       │   └── DashboardPage.tsx
│       └── index.ts
├── widgets/
│   ├── header/
│   │   ├── ui/
│   │   │   └── Header.tsx
│   │   └── index.ts
│   └── sidebar/
│       ├── ui/
│       │   └── Sidebar.tsx
│       └── index.ts
├── features/
│   ├── auth/
│   │   ├── ui/
│   │   │   ├── LoginForm.tsx
│   │   │   └── LogoutButton.tsx
│   │   ├── model/
│   │   │   └── authSlice.ts
│   │   ├── api/
│   │   │   └── authApi.ts
│   │   └── index.ts
│   └── search/
│       ├── ui/
│       │   └── SearchBar.tsx
│       ├── model/
│       │   └── searchModel.ts
│       └── index.ts
├── entities/
│   ├── user/
│   │   ├── model/
│   │   │   └── types.ts
│   │   ├── api/
│   │   │   └── userApi.ts
│   │   └── index.ts
│   └── post/
│       ├── ui/
│       │   └── PostCard.tsx
│       ├── model/
│       │   └── types.ts
│       └── index.ts
└── shared/
    ├── ui/
    │   ├── Button/
    │   ├── Input/
    │   └── Modal/
    ├── api/
    │   └── client.ts
    ├── config/
    │   └── constants.ts
    └── lib/
        └── utils.ts

Layer

Layer는 모든 FSD 프로젝트의 표준 최상위 폴더입니다.

  1. App* - Routing, Entrypoint, Global Styles, Provider 등 앱을 실행하는 모든 요소
  2. Processes(더 이상 사용되지 않음) - 페이지 간 복합 시나리오
  3. Pages - 전체 page 또는 중첩 Routing의 핵심 영역
  4. Widgets - 독립적으로 동작하는 대형 UI·기능 블록
  5. Features - 제품 전반에서 재사용되는 비즈니스 기능
  6. Entities - user, product 같은 핵심 도메인 Entity
  7. Shared* - 프로젝트 전반에서 재사용되는 일반 유틸리티 - App·Shared Layer는 Slice 없이 곧바로 Segment로 구성됩니다.
  • 상위 Layer의 모듈은 자신보다 하위 Layer만 참조할 수 있습니다.

Slice

Slice는 Layer 내부를 비즈니스 도메인별로 나눕니다. 이름·개수에 제한이 없으며, 같은 Layer 내 다른 Slice를 참조할 수 없습니다. 이 규칙이 높은 응집도와 낮은 결합도를 보장합니다.

Segment

Slice와 App·Shared Layer는 Segment로 세분화되어, 기술적 목적에 따라 코드를 그룹화합니다. 일반적으로 다음과 같은 Segment를 사용합니다

  • ui - UI components, date formatter, styles 등 UI 표현과 직접 관련된 코드
  • api - request functions, data types, mappers 등 백엔드 통신 및 데이터 로직
  • model - schema, interfaces, store, business logic 등 애플리케이션 도메인 모델
  • lib - 해당 Slice에서 여러 모듈이 함께 사용하는 공통 library code
  • config - configuration files, feature flags 등 환경·기능 설정

대부분의 Layer에서는 위 다섯 Segment로 충분합니다. 필요하다면 App 또는 Shared Layer에서만 추가 Segment를 정의하세요. (필수 규칙은 아닙니다.)

그래프 뷰

백링크