FSD아키텍처(Feature-Sliced Design) 가이드

📌 FSD(Feature-Sliced Design)란?

프론트엔드 프로젝트의 규모가 커질수록 코드베이스의 복잡도는 기하급수적으로 증가합니다. "이 컴포넌트는 어디에 있지?", "이 기능을 수정하면 어디가 영향받을까?", "새로운 팀원이 프로젝트 구조를 이해하는데 얼마나 걸릴까?" 같은 고민이 끊이지 않습니다.

Feature-Sliced Design(FSD)은 이러한 문제를 해결하기 위해 탄생한 프론트엔드 아키텍처 방법론입니다. 직역하면 '기능 분할 설계'로, 코드를 체계적으로 구성하기 위한 규칙과 관례의 집합이라고 할 수 있습니다.

🎯 FSD가 해결하는 문제

기존 프론트엔드 프로젝트의 고질적인 문제들

1. 불명확한 코드 구조 📂
   • 컴포넌트, 훅, 유틸리티가 뒤섞여 있어 찾기 어려움
   • 각자의 스타일로 폴더를 구성해 일관성 부족
2. 높은 결합도 🔗
   • 한 기능을 수정하면 예상치 못한 곳에서 버그 발생
   • 코드 간 의존성이 복잡하게 얽혀있음
3. 낮은 재사용성 ♻️
   • 비슷한 기능을 여러 곳에서 중복으로 구현
   • 공통 로직을 추출하기 어려움
4. 확장의 어려움 📈
   • 새로운 기능을 추가할 때마다 기존 구조와 충돌
   • 리팩토링이 두려워 기술 부채가 쌓임

FSD는 이 모든 문제를 계층화된 구조와 명확한 의존성 규칙으로 해결합니다.

🏗️ FSD의 핵심 구조: 3단계 계층

FSD는 프로젝트를 Layer(레이어) → Slice(슬라이스) → Segment(세그먼트)의 3단계로 구조화합니다.

📦 프로젝트
├── 📂 Layer (레이어) - 최상위 계층
│   ├── 📂 Slice (슬라이스) - 비즈니스 도메인별 분리
│   │   ├── 📂 Segment (세그먼트) - 기능별 분리
│   │   │   └── 📄 파일들

📚 Layer(레이어): 7가지 계층의 세계

FSD는 총 7개의 레이어를 정의하지만, 실제로는 6개만 사용합니다. (Processes 레이어는 현재 사용되지 않음)

계층 구조 한눈에 보기

⬆️ 상위 레이어 (사용자와 가까움)
     │
┌────┴────┐
│   App   │  🏠 애플리케이션 진입점 & 전역 설정
└────┬────┘
     │
┌────┴────┐
│  Pages  │  📄 개별 페이지 (라우트 단위)
└────┬────┘
     │
┌────┴────┐
│ Widgets │  🧩 독립적인 UI 블록 (재사용 가능)
└────┬────┘
     │
┌────┴─────┐
│ Features │  ⚡ 비즈니스 기능 (사용자 행동)
└────┬─────┘
     │
┌────┴─────┐
│ Entities │  📦 비즈니스 엔티티 (데이터 모델)
└────┬─────┘
     │
┌────┴────┐
│ Shared  │  🔧 공통 리소스 (UI 컴포넌트, 유틸)
└─────────┘
     │
     ⬇️ 하위 레이어 (기술적 기반)

1️⃣ App Layer (애플리케이션)

역할: 프로젝트의 진입점이자 전역 설정을 관리하는 최상위 레이어

포함 요소:

• 라우팅 설정 🛣️
• 전역 스타일 🎨
• Provider (Redux, Theme 등) 🔌
• 전역 상태 초기화 ⚙️

특징: 슬라이스 없이 세그먼트만 포함

📂 app/
├── 📂 providers/       // Redux Provider, Theme Provider
├── 📂 styles/          // Global CSS, Reset CSS
├── 📂 router/          // React Router 설정
└── 📄 index.tsx        // 앱 진입점

실제 예시:

// app/index.tsx
import { ThemeProvider } from '@/app/providers/theme'
import { Router } from '@/app/router'

export const App = () => (
  <ThemeProvider>
    <Router />
  </ThemeProvider>
)

2️⃣ Pages Layer (페이지)

역할: URL 라우트에 매핑되는 개별 페이지를 구성

특징:

• 각 페이지는 하나의 슬라이스
• Widgets와 Features를 조합해 완성된 페이지 구성
• 복잡한 비즈니스 로직보다는 UI 조합에 집중

📂 pages/
├── 📂 home/            // 홈 페이지 ("/")
│   ├── 📂 ui/
│   └── 📄 index.ts
├── 📂 user-profile/    // 프로필 페이지 ("/profile/:id")
│   ├── 📂 ui/
│   └── 📄 index.ts
└── 📂 settings/        // 설정 페이지 ("/settings")
    ├── 📂 ui/
    └── 📄 index.ts

실제 예시:

// pages/user-profile/ui/UserProfilePage.tsx
import { UserHeader } from '@/widgets/user-header'
import { UserPosts } from '@/widgets/user-posts'
import { FollowButton } from '@/features/follow-user'

export const UserProfilePage = () => (
  <div>
    <UserHeader />
    <FollowButton />
    <UserPosts />
  </div>
)

3️⃣ Widgets Layer (위젯)

역할: 독립적으로 작동하는 큰 UI 블록

특징:

• 여러 Features와 Entities를 조합
• 다양한 페이지에서 재사용 가능
• 자체적으로 완결된 기능 제공

예시:

• 검색바 (SearchBar) 🔍
• 헤더/네비게이션 (Header, Sidebar) 📍
• 댓글 섹션 (CommentSection) 💬
• 대시보드 카드 (DashboardCard) 📊

📂 widgets/
├── 📂 user-header/     // 사용자 헤더 위젯
│   ├── 📂 ui/
│   │   └── UserHeader.tsx
│   ├── 📂 model/
│   └── 📄 index.ts
└── 📂 post-feed/       // 포스트 피드 위젯
    ├── 📂 ui/
    ├── 📂 model/
    └── 📄 index.ts

실제 예시:

// widgets/user-header/ui/UserHeader.tsx
import { UserAvatar } from '@/entities/user'
import { FollowButton } from '@/features/follow-user'
import { EditProfileButton } from '@/features/edit-profile'

export const UserHeader = ({ userId }) => (
  <header>
    <UserAvatar userId={userId} />
    <FollowButton userId={userId} />
    <EditProfileButton userId={userId} />
  </header>
)

4️⃣ Features Layer (기능)

역할: 재사용 가능한 비즈니스 기능 단위

특징:

• 사용자 행동과 직접 연결된 기능
• 독립적으로 동작 가능
• 여러 페이지/위젯에서 재사용

예시:

• 좋아요 버튼 (LikePost) ❤️
• 팔로우/언팔로우 (FollowUser) 👥
• 댓글 작성 (AddComment) 💬
• 로그인/로그아웃 (AuthUser) 🔐

📂 features/
├── 📂 follow-user/     // 팔로우 기능
│   ├── 📂 ui/
│   │   └── FollowButton.tsx
│   ├── 📂 model/       // 팔로우 상태 관리
│   ├── 📂 api/         // 팔로우 API 호출
│   └── 📄 index.ts
└── 📂 like-post/       // 좋아요 기능
    ├── 📂 ui/
    ├── 📂 model/
    ├── 📂 api/
    └── 📄 index.ts

실제 예시:

// features/follow-user/ui/FollowButton.tsx
import { useFollowUser } from '../model/useFollowUser'
import { Button } from '@/shared/ui/button'

export const FollowButton = ({ userId }) => {
  const { isFollowing, toggle } = useFollowUser(userId)
  
  return (
    <Button onClick={toggle}>
      {isFollowing ? '언팔로우' : '팔로우'}
    </Button>
  )
}

5️⃣ Entities Layer (엔티티)

역할: 비즈니스의 핵심 데이터 모델 관리

특징:

• 프로젝트의 핵심 도메인 객체
• 데이터 구조와 기본 로직 포함
• 사용자 행동과 무관한 순수 데이터 계층

예시:

• User (사용자) 👤
• Post (게시물) 📝
• Comment (댓글) 💬
• Product (상품) 🛒

📂 entities/
├── 📂 user/            // 사용자 엔티티
│   ├── 📂 ui/
│   │   ├── UserCard.tsx
│   │   └── UserAvatar.tsx
│   ├── 📂 model/       // 타입 정의, 상태 관리
│   ├── 📂 api/         // 사용자 데이터 fetch
│   └── 📄 index.ts
└── 📂 post/            // 게시물 엔티티
    ├── 📂 ui/
    ├── 📂 model/
    ├── 📂 api/
    └── 📄 index.ts

실제 예시:

// entities/user/model/types.ts
export interface User {
  id: string
  name: string
  email: string
  avatar: string
  followersCount: number
}

// entities/user/ui/UserCard.tsx
import { User } from '../model/types'

export const UserCard = ({ user }: { user: User }) => (
  <div className="user-card">
    <img src={user.avatar} alt={user.name} />
    <h3>{user.name}</h3>
    <p>{user.followersCount} followers</p>
  </div>
)

6️⃣ Shared Layer (공유)

역할: 프로젝트 전반에서 재사용되는 공통 리소스

특징:

• 비즈니스 로직과 무관한 순수 기술 계층
• 슬라이스 없이 세그먼트만 포함
• 필요할 때마다 추가하는 방식

포함 요소:

• UI 컴포넌트 (Button, Input, Modal) 🎨
• 유틸리티 함수 (날짜 포맷, 문자열 처리) 🔧
• API 클라이언트 (Axios 인스턴스) 🌐
• 상수/설정 (환경 변수, 설정 값) ⚙️

📂 shared/
├── 📂 ui/              // 기본 UI 컴포넌트
│   ├── button/
│   ├── input/
│   ├── modal/
│   └── index.ts
├── 📂 lib/             // 유틸리티 함수
│   ├── format/
│   ├── validation/
│   └── index.ts
├── 📂 api/             // API 클라이언트
│   └── client.ts
└── 📂 config/          // 상수, 설정
    └── constants.ts

실제 예시:

// shared/ui/button/Button.tsx
export const Button = ({ children, variant = 'primary', ...props }) => (
  <button 
    className={`btn btn-${variant}`}
    {...props}
  >
    {children}
  </button>
)

// shared/lib/format/date.ts
export const formatDate = (date: Date) => {
  return new Intl.DateTimeFormat('ko-KR').format(date)
}

🔒 FSD의 핵심 원칙: 단방향 의존성

의존성 규칙 (Dependency Rule)

FSD의 가장 중요한 규칙은 "상위 레이어만 하위 레이어에 의존할 수 있다"는 것입니다.

App ──────────────────────────┐
  ↓                            │
Pages ────────────────────┐    │
  ↓                       │    │
Widgets ──────────────┐   │    │
  ↓                   │   │    │
Features ──────────┐  │   │    │
  ↓                │  │   │    │
Entities ────────┐ │  │   │    │
  ↓              │ │  │   │    │
Shared ←─────────┴─┴──┴───┴────┘

✅ 허용되는 의존성

// ✅ Pages → Widgets
import { UserHeader } from '@/widgets/user-header'

// ✅ Widgets → Features
import { FollowButton } from '@/features/follow-user'

// ✅ Features → Entities
import { User } from '@/entities/user'

// ✅ Entities → Shared
import { Button } from '@/shared/ui/button'

❌ 금지되는 의존성

// ❌ Entities → Features (하위 → 상위)
import { FollowButton } from '@/features/follow-user'

// ❌ Shared → Entities (하위 → 상위)
import { User } from '@/entities/user'

// ❌ 같은 레이어의 다른 슬라이스 참조
// features/follow-user → features/like-post
import { LikeButton } from '@/features/like-post'

🎯 이 규칙의 장점

1. 예측 가능한 코드 흐름 🔮
   • 의존성이 항상 한 방향으로만 흐름
   • 순환 참조 방지
2. 안전한 리팩토링 🔧
   • 하위 레이어 수정 시 상위에만 영향
   • 상위 레이어 수정은 다른 레이어에 무영향
3. 명확한 책임 분리 📋
   • 각 레이어의 역할이 명확
   • 코드를 어디에 둘지 고민 감소

---

🍕 Slice(슬라이스): 비즈니스 도메인별 분리

슬라이스란?

슬라이스는 비즈니스 도메인을 기준으로 코드를 나누는 두 번째 계층입니다.

주의: App과 Shared 레이어는 슬라이스를 가지지 않습니다!

슬라이스 명명 규칙

// ✅ 좋은 슬라이스 이름 (비즈니스 도메인)
features/
  follow-user/        // 사용자 팔로우
  like-post/          // 게시물 좋아요
  edit-profile/       // 프로필 수정

entities/
  user/               // 사용자
  post/               // 게시물
  comment/            // 댓글

// ❌ 나쁜 슬라이스 이름 (기술적 구분)
features/
  api/
  components/
  hooks/

슬라이스 독립성 원칙

핵심 규칙: 같은 레이어의 다른 슬라이스를 참조할 수 없습니다!

// ❌ 금지: 같은 레이어 간 참조
// features/follow-user/ui/FollowButton.tsx
import { LikeButton } from '@/features/like-post'

// ✅ 허용: 하위 레이어 참조
// features/follow-user/ui/FollowButton.tsx
import { User } from '@/entities/user'
import { Button } from '@/shared/ui/button'

이 규칙이 중요한 이유:

1. 낮은 결합도 🔓
   • 각 슬라이스는 독립적으로 개발/테스트 가능
   • 한 슬라이스 수정이 다른 슬라이스에 영향 없음
2. 높은 응집도 🎯
   • 관련된 코드는 한 슬라이스에 모임
   • 기능별로 완결된 구조
3. 명확한 경계 🚧
   • 각 비즈니스 도메인의 경계가 명확
   • 코드 소유권이 분명

---

📦 Segment(세그먼트): 기능별 분리

세그먼트란?

세그먼트는 슬라이스 내부를 기능적 역할로 나누는 세 번째 계층입니다.

일반적인 세그먼트 종류

📂 user-slice/
├── 📂 ui/              // 🎨 UI 컴포넌트
│   ├── UserCard.tsx
│   └── UserAvatar.tsx
├── 📂 model/           // 📊 상태 관리 & 비즈니스 로직
│   ├── types.ts
│   ├── store.ts
│   └── hooks.ts
├── 📂 api/             // 🌐 API 통신
│   ├── getUser.ts
│   └── updateUser.ts
├── 📂 lib/             // 🔧 유틸리티 함수
│   └── validation.ts
└── 📄 index.ts         // 📤 Public API

각 세그먼트의 역할

1. UI 세그먼트 🎨

역할: 사용자에게 보이는 컴포넌트

// features/follow-user/ui/FollowButton.tsx
import { useFollowUser } from '../model/useFollowUser'
import { Button } from '@/shared/ui/button'

export const FollowButton = ({ userId }: { userId: string }) => {
  const { isFollowing, toggle, isLoading } = useFollowUser(userId)
  
  return (
    <Button 
      onClick={toggle}
      disabled={isLoading}
      variant={isFollowing ? 'secondary' : 'primary'}
    >
      {isFollowing ? '팔로잉' : '팔로우'}
    </Button>
  )
}

2. Model 세그먼트 📊

역할: 상태 관리, 비즈니스 로직, 타입 정의

// features/follow-user/model/types.ts
export interface FollowState {
  followingIds: string[]
  isLoading: boolean
  error: string | null
}

// features/follow-user/model/useFollowUser.ts
import { useState } from 'react'
import { followUserApi, unfollowUserApi } from '../api'

export const useFollowUser = (userId: string) => {
  const [isFollowing, setIsFollowing] = useState(false)
  const [isLoading, setIsLoading] = useState(false)
  
  const toggle = async () => {
    setIsLoading(true)
    try {
      if (isFollowing) {
        await unfollowUserApi(userId)
      } else {
        await followUserApi(userId)
      }
      setIsFollowing(!isFollowing)
    } finally {
      setIsLoading(false)
    }
  }
  
  return { isFollowing, toggle, isLoading }
}

3. API 세그먼트 🌐

역할: 서버와의 데이터 통신

// features/follow-user/api/followUser.ts
import { apiClient } from '@/shared/api/client'

export const followUserApi = (userId: string) => {
  return apiClient.post(`/users/${userId}/follow`)
}

export const unfollowUserApi = (userId: string) => {
  return apiClient.delete(`/users/${userId}/follow`)
}

4. Lib 세그먼트 🔧

역할: 해당 슬라이스에서만 사용하는 유틸리티

// features/edit-profile/lib/validation.ts
export const validateUsername = (username: string): boolean => {
  return username.length >= 3 && username.length <= 20
}

export const validateEmail = (email: string): boolean => {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}

🔑 Public API: 외부 인터페이스 관리

Public API란?

각 슬라이스는 index.ts 파일을 통해 외부에 노출할 것만 선별적으로 공개합니다.

장점

1. 캡슐화 📦
   • 내부 구현을 숨기고 인터페이스만 노출
2. 리팩토링 안정성 🔒
   • 내부 구조 변경 시 외부 영향 최소화
3. 명확한 계약 📋
   • 무엇을 사용할 수 있는지 명확

예시

// features/follow-user/index.ts

// ✅ 외부에 공개할 것만 export
export { FollowButton } from './ui/FollowButton'
export { useFollowUser } from './model/useFollowUser'
export type { FollowState } from './model/types'

// ❌ 내부 구현은 공개하지 않음
// export { followUserApi } from './api/followUser'

// 다른 레이어에서 사용
import { FollowButton, useFollowUser } from '@/features/follow-user'

// ❌ 금지: 내부 파일 직접 접근
// import { FollowButton } from '@/features/follow-user/ui/FollowButton'

---

Feature-Sliced Design(FSD)는 대규모 프론트엔드 애플리케이션의 유지보수성과 확장성을 높이기 위해 고안된 아키텍처 방법론이다. FSD의 기본 개념과 원칙, 그리고 사용 시의 이점을 정리하면 다음과 같다.

 

참고문헌

https://velog.io/@clydehan/FSDFeature-Sliced-Design-%EC%99%84%EB%B2%BD-%EA%B0%80%EC%9D%B4%EB%93%9C

Overview | Feature-Sliced Design

Feature-Sliced Design: The Best Frontend Architecture