conduit
A place to share your knowledge.
{article.author.username}
{new Date(article.createdAt).toLocaleDateString(undefined, {
dateStyle: "long",
})}
{article.title}
{article.description}
Read more...-
{article.tagList.map((tag) => (
- {tag} ))}
conduit
A place to share your knowledge.
{articles.articles.map((article) => (
conduit
A place to share your knowledge.
{articles.articles.map((article) => (
Popular Tags
conduit
A place to share your knowledge.
{articles.articles.map((article) => (
Popular Tags
Sign up
Have an account?
{registerData?.error && (-
{registerData.error.errors.body.map((error) => (
- {error} ))}
Sign in
Need an account?
{signInData?.error && (-
{signInData.error.errors.body.map((error) => (
- {error} ))}
Popular Tags
conduit
A place to share your knowledge.
{article.author.username}
{new Date(article.createdAt).toLocaleDateString(undefined, {
dateStyle: "long",
})}
{article.title}
{article.description}
Read more...-
{article.tagList.map((tag) => (
- {tag} ))}
{article.article.title}
{article.article.body}
-
{article.article.tagList.map((tag) => (
- {tag} ))}
{currentUser !== null ? (
) : (
)}
{comments.comments.map((comment) => (
{comment.author.username}
{comment.createdAt}
{comment.author.username === currentUser?.username && (
)}
))}
);
}
```
이것으로 우리의 글 읽기 페이지도 완성되었습니다! 이제 작성자를 팔로우하고, 글에 좋아요를 누르고, 댓글을 남기는 버튼들이 예상대로 작동해야 합니다.
기능하는 좋아요와 팔로우 버튼이 있는 글 읽기 페이지
### 글 작성 페이지[](#글-작성-페이지 "해당 헤딩으로 이동")
이것은 이 튜토리얼에서 다룰 마지막 페이지이며, 여기서 가장 흥미로운 부분은 폼 데이터를 어떻게 검증할 것인가 입니다.
페이지 자체인 `article-edit/ui/ArticleEditPage.tsx`는 꽤 간단할 것이며, 추가적인 복잡성은 다른 두 개의 컴포넌트로 숨겨질 것입니다.
pages/article-edit/ui/ArticleEditPage.tsx
```
import { Form, useLoaderData } from "@remix-run/react";
import type { loader } from "../api/loader";
import { TagsInput } from "./TagsInput";
import { FormErrors } from "./FormErrors";
export function ArticleEditPage() {
const article = useLoaderDataSign in or Sign up to add comments on this article.
{comment.body}
-
{actionData.errors.map((error) => (
- {error} ))}
{tagListState.map((tag) => (
[" ", "Enter"].includes(e.key) && removeTag(tag)
}
onClick={() => removeTag(tag)}
>{" "}
{tag}
))}
);
}
```
이제 API 부분입니다. 로더는 URL을 살펴보고, 글 슬러그가 포함되어 있다면 기존 글을 수정하는 것이므로 해당 데이터를 로드해야 합니다. 그렇지 않으면 아무것도 반환하지 않습니다. 그 로더를 만들어 봅시다.
pages/article-edit/api/loader.ts
```
import { json, type LoaderFunctionArgs } from "@remix-run/node";
import type { FetchResponse } from "openapi-fetch";
import { GET, requireUser } from "shared/api";
async function throwAnyErrors이렇게 하면 애플리케이션 전체에서 손쉽게 재사용할 수 있고, 빠른 프로토타이핑이 가능합니다. 대부분의 프로젝트에서는 이 폴더 구조와 client.ts 설정만으로 충분합니다. 일반적인 파일 구조 예시: * 📂 shared * 📂 api * 📄 client.ts * 📄 index.ts * 📂 endpoints * 📄 login.ts `client.ts` 파일은 HTTP request 관련 설정을 **한 곳에서** 관리합니다.
`fetch()` 또는 `axios` instance에 공통 설정을 적용하여 다음을 처리합니다: * 백엔드 기본 URL * Default headers (예: 인증 header) * 데이터 직렬화 아래 예시를 참고하세요. * Axios * Fetch shared/api/client.ts ``` // Axios 예시 import axios from 'axios'; export const client = axios.create({ baseURL: 'https://your-api-domain.com/api/', timeout: 5000, headers: { 'X-Custom-Header': 'my-custom-value' } }); ``` shared/api/client.ts ``` export const client = { async post(endpoint: string, body: any, options?: RequestInit) { const response = await fetch(`https://your-api-domain.com/api${endpoint}`, { method: 'POST', body: JSON.stringify(body), ...options, headers: { 'Content-Type': 'application/json', 'X-Custom-Header': 'my-custom-value', ...options?.headers, }, }); return response.json(); } // ... other methods like put, delete, etc. }; ``` `shared/api/endpoints` 폴더에 endpoint별 request 함수를 정리하세요. note 예시의 가독성을 위해 form handling과 검증(Zod·Valibot 등)은 생략했습니다. 자세한 내용은 [Type Validation and Schemas](/documentation/kr/docs/guides/examples/types.md#type-validation-schemas-and-zod)에서 확인하세요. shared/api/endpoints/login.ts ``` import { client } from '../client'; export interface LoginCredentials { email: string; password: string; } export function login(credentials: LoginCredentials) { return client.post('/login', credentials); } ``` `shared/api/index.ts`에서 request 함수와 타입을 내보내세요: shared/api/index.ts ``` export { client } from './client'; // If you want to export the client itself export { login } from './endpoints/login'; export type { LoginCredentials } from './endpoints/login'; ``` ## Slice-specific API Requests[](#slice-specific-api-requests "해당 헤딩으로 이동") 특정 페이지나 feature에서만 쓰이는 request는 해당 slice의 api 폴더에 두어 정리하세요. 이렇게 하면 slice별 로직이 깔끔하게 분리됩니다. * 📂 pages * 📂 login * 📄 index.ts * 📂 api * 📄 login.ts * 📂 ui * 📄 LoginPage.tsx pages/login/api/login.ts ``` import { client } from 'shared/api'; interface LoginCredentials { email: string; password: string; } export function login(credentials: LoginCredentials) { return client.post('/login', credentials); } ``` 이 함수는 재사용 가능성이 낮으므로, slice의 public API로 내보낼 필요가 없습니다. note entities layer에 API request와 response 타입을 배치하지 마세요. 백엔드 response 타입과 프론트엔드 `entities` 타입이 다를 수 있습니다. `shared/api`나 slice의 `api` 폴더에서 데이터를 변환하고, entities는 프론트엔드 관점에 집중하도록 설계하세요. ## API 타입과 클라이언트 자동 생성[](#api-타입과-클라이언트-자동-생성 "해당 헤딩으로 이동") 백엔드에 OpenAPI 스펙이 있다면 [orval](https://orval.dev/)이나 [openapi-typescript](https://openapi-ts.dev/) 같은 도구로 API 타입과 request 함수를 생성할 수 있습니다. 생성된 코드는 `shared/api/openapi` 등에 두고 `README.md`에 생성 방법과 타입 설명을 문서화하세요. ## 서버 상태 라이브러리 연동[](#서버-상태-라이브러리-연동 "해당 헤딩으로 이동") [TanStack Query (React Query)](https://tanstack.com/query/latest)나 [Pinia Colada](https://pinia-colada.esm.dev/) 같은 서버 상태 관리 라이브러리를 사용할 때는 slice 간 타입이나 cache key를 공유해야 할 수 있습니다. 이럴 때는 `shared` layer에 다음을 배치하세요. * API 데이터 타입 (API data types) * 캐시 키 (cache keys) * 공통 query/mutation 옵션 (common query/mutation options) --- # Authentication 일반적으로 **인증(Authentication)** 플로우는 세 단계로 구성됩니다. 1. **Credential 입력 수집** — 아이디, 패스워드(또는 OAuth redirect URL)를 입력받습니다. 2. **백엔드 Endpoint 호출** — `/login`, `/oauth/callback`, `/2fa` 등 로그인 관련 API endpoint에 request을 보냅니다. 3. **Token 저장** — 발급된 token을 **cookie** 또는 **store** 에 저장해 이후 request에 사용합니다. ## 1. Credential 입력 수집[](#1-credential-입력-수집 "해당 헤딩으로 이동") > OAuth 로그인을 사용한다면 **2단계를 건너뛰고 바로 [token 저장](#how-to-store-the-token-for-authenticated-requests)** 단계로 이동합니다. ### 1‑1. 로그인 전용 페이지[](#11-로그인전용-페이지 "해당 헤딩으로 이동") 웹 애플리케이션에서는 보통 **/login** 같은 로그인 전용 페이지를 제공해 사용자 이름과 패스워드를 입력받습니다.
페이지가 단순하므로 추가 **decomposition(구조 분할)** 이 필요 없으며, 로그인 폼과 회원가입 폼을 하나의 컴포넌트로 만들어 재사용할 수 있습니다. * 📂 pages * 📂 login * 📂 ui * 📄 LoginPage.tsx (or your framework's component file format) * 📄 RegisterPage.tsx * 📄 index.ts * other pages… * `LoginPage`·`RegisterPage` 두 컴포넌트를 **분리**해 구현하고, 필요 시 `index.ts`에서 export 합니다. * 각 컴포넌트는 **form elements**와 form submit handler만 포함해 단순성을 유지합니다. ### 1‑2. 로그인 dialog 만들기[](#12-로그인dialog-만들기 "해당 헤딩으로 이동") 모든 페이지에서 호출할 로그인 dialog가 필요하다면 **재사용 가능한 widget**으로 구현하세요.
widget으로 만들면 과도하게 구조를 쪼개지 않으면서도, 어떤 페이지에서도 동일한 dialog을 쉽게 띄울 수 있습니다. * 📂 widgets * 📂 login-dialog * 📂 ui * 📄 LoginDialog.tsx * 📄 index.ts * other widgets… > 이후 설명은 로그인 전용 페이지를 기준으로 하지만, 동일한 원칙이 dialog widget에도 적용됩니다. ### 1‑3. Client‑side Validation[](#13-clientsidevalidation "해당 헤딩으로 이동") 회원가입 페이지에서 입력 오류를 즉시 알려 주는 것이 UX에 도움이 됩니다.
검증 schema는 `pages/login/model` segment에 정의하고 `ui` segment에서 재사용하세요.
아래 예시는 [Zod](https://zod.dev) 로 타입과 값을 동시에 검증하는 패턴입니다. pages/login/model/registration-schema.ts ``` import { z } from "zod"; export const registrationData = z.object({ email: z.string().email(), password: z.string().min(6), confirmPassword: z.string(), }).refine((data) => data.password === data.confirmPassword, { message: "비밀번호가 일치하지 않습니다", path: ["confirmPassword"], }); ``` 그런 다음, ui segment에서 이 schema를 사용해 사용자 입력을 검증할 수 있습니다: pages/login/ui/RegisterPage.tsx ``` import { registrationData } from "../model/registration-schema"; function validate(formData: FormData) { const data = Object.fromEntries(formData.entries()); try { registrationData.parse(data); } catch (error) { // TODO: Show error message to the user } } export function RegisterPage() { return ( ) } ``` ## 2. Send credentials[](#2-send-credentials "해당 헤딩으로 이동") 사용자 **credentials**(e‑mail, password)을 백엔드 **endpoint**로 전송하는 request 함수을 생성합니다.
이 함수는 Zustand, Redux Toolkit, **TanStack Query** `useMutation` 등에서 호출할 수 있습니다. ### 2‑1. 함수 placement[](#21-함수-placement "해당 헤딩으로 이동") | 목적 | 권장 위치 | 이유 | | ----------- | ----------------- | -------------------------- | | 전역 재사용 | `shared/api` | 모든 slice에서 import 가능 | | 로그인 전용 | `pages/login/api` | slice 내부 capsule 유지 | #### `shared/api`에 저장하기[](#sharedapi에-저장하기 "해당 헤딩으로 이동") 모든 API request을 `shared/api`에 모아 endpoint로 그룹화합니다. * 📂 shared * 📂 api * 📂 endpoints * 📄 login.ts * other endpoint functions… * 📄 client.ts * 📄 index.ts `📄 client.ts`는 원시 request 함수(`fetch` 등)를 감싸 **기본 URL, 공통 헤더, 직렬화** 등을 처리합니다. shared/api/endpoints/login.ts ``` import { POST } from "../client"; export function login({ email, password }: { email: string, password: string }) { return POST("/login", { email, password }); } ``` shared/api/index.ts ``` export { login } from "./endpoints/login"; ``` #### page의 `api` segment에 저장하기[](#page의-api-segment에-저장하기 "해당 헤딩으로 이동") 로그인 요청이 로그인 페이지에서만 필요하다면, 해당 페이지의 `api` segment에 함수를 두십시오. * 📂 pages * 📂 login * 📂 api * 📄 login.ts * 📂 ui * 📄 LoginPage.tsx * 📄 index.ts * other pages… pages/login/api/login.ts ``` import { POST } from "shared/api"; export function login({ email, password }: { email: string, password: string }) { return POST("/login", { email, password }); } ``` > 이 함수는 로그인 페이지 내부에서만 사용하므로 index.ts에 재-export할 필요가 없습니다. ### Two‑Factor Auth (2FA)[](#twofactorauth2fa "해당 헤딩으로 이동") 1. `/login` 응답에 `has2FA` 플래그가 있으면 `/login/2fa` 페이지로 redirect합니다. 2. 2FA 페이지와 관련 API는 `pages/login` slice에 함께 둡니다. 3. `/2fa/verify` 같은 별도 endpoint를 호출하는 함수를 `shared/api` 또는 `pages/login/api`에 배치합니다. ## Authenticated Requests를 위한 token 저장[](#how-to-store-the-token-for-authenticated-requests "해당 헤딩으로 이동") 로그인, 비밀번호, OAuth, 2단계 인증 등 어떤 방식이든 인증 API 호출의 **응답(response)** 으로 token을 받습니다.
이 token을 저장해 두면 이후 **모든 API 요청(request)** 에 token을 자동으로 포함해 인증을 통과할 수 있습니다. 웹 애플리케이션에서 token을 저장하기에 **가장 바람직한 방법은 cookie**입니다. cookie를 사용하면 token을 직접 저장하거나 관리할 필요가 없으므로, 프론트엔드 아키텍처 차원에서 별도의 고려가 거의 필요 없습니다. 프레임워크에 서버 사이드 기능이 있다면(예: [Remix](https://remix.run)), 서버 측 cookie 로직을 `shared/api`에 두세요. Remix 예제는 [튜토리얼의 Authentication 섹션](/documentation/kr/docs/get-started/tutorial.md#authentication)을 참고하면 됩니다. 그러나 cookie를 사용할 수 없는 환경도 있습니다. 이 경우 token을 **직접** 저장하고, 만료 시 token을 갱신(Refresh)하는 로직도 구현해야 합니다. FSD에서는 **어느 layer 또는 어느 segment에** token을 저장할지, 그리고 **어떻게** 앱 전역에 노출할지 다양한 선택지가 존재합니다. ### 3‑1. Shared[](#31-shared "해당 헤딩으로 이동") 이 접근법은 `shared/api`에 정의한 **API 클라이언트**와 잘 어울리는 방식입니다. token을 module scope나 reactive store에 담아 두면, 인증이 필요한 다른 API 호출 함수에서 그대로 참조할 수 있습니다. token 자동 재발급(Refresh)는 클라이언트 **middleware**로 구현합니다. 1. 로그인 시 **access token, refresh token** 저장 2. 인증이 필요한 request 실행 3. 만료 코드가 오면 refresh token으로 새 token을 받아 저장하고 **기존 request**을 재시도 #### Token 관리 분리 전략[](#token-관리-분리-전략 "해당 헤딩으로 이동") * **전담 segment 부재**
token 저장, 재발급 로직이 request 로직과 같은 파일에 섞이면
규모가 커질수록 유지보수가 어려워집니다.
→ **request 함수, 클라이언트**는 `shared/api`,
**token 관리 로직**은 `shared/auth` segment로 분리하세요. * **token과 사용자 정보를 함께 받는 경우**
백엔드가 token과 함께 **현재 사용자 정보**를 반환한다면 1. 별도 store에 함께 저장하거나 2. `/me`·`/users/current` 엔드포인트를 다시 호출해 가져올 수 있습니다. ### 3‑2. Entities[](#32-entities "해당 헤딩으로 이동") FSD 프로젝트에서는 **User entity**(또는 **Current User entity**)를 두는 경우가 많습니다.
두 entity가 하나로 합쳐져도 무방합니다. note **Current User**는 “viewer” 또는 “me”라고도 부릅니다.
권한·개인 정보가 있는 **단일 인증 사용자**와, 공개 목록에 나타나는 **모든 사용자 목록**를 구분하기 위해서입니다. #### Token을 User Entities에 저장하기[](#token을-user-entities에-저장하기 "해당 헤딩으로 이동") `model` segment에 **reactive store**를 만들고, token과 user 객체를 함께 보관하세요. API 클라이언트는 일반적으로 `shared/api` 정의되거나 entity 전체에 분산되어 있습니다. 따라서 주요 과제는 layer의 import 규칙([import rule on layers](/documentation/kr/docs/reference/layers.md#import-rule-on-layers))을 위반하지 않으면서 다른 request에서도 token을 사용할 수 있도록 하는 것입니다. > Layer 규칙 — Slice의 module은 **자기보다 아래 layer**의 Slice만 import할 수 있습니다. ##### 해결 방법[](#해결-방법 "해당 헤딩으로 이동") 1. **request마다 token을 직접 넘기기** * 구현은 단순하지만 반복적이고, 타입 안전성이 없으면 실수 위험이 큽니다. * `shared/api`에 middleware pattern을 적용하기도 어렵습니다. 2. **앱 전역(Context / `localStorage`)에 노출** * token key는 `shared/api`에 두고, token store는 User entity에서 export합니다. * Context Provider는 App layer에 배치합니다. * 설계 자유도가 높지만, 상위 layer에 **암묵적 의존성**이 생깁니다.
⇒ Context나 `localStorage`가 누락된 경우 **명확한 에러**를 제공해 주세요. 3. **token이 바뀔 때마다 API 클라이언트에 업데이트** * store **subscription**으로 "token 변경 → 클라이언트 상태 업데이트”를 수행합니다. * 방법 2와 마찬가지로 암묵적 의존성이 있으나, * 방법 2는 **선언형(pull)**, * 방법 3은 **명령형(push)** 접근입니다. token을 노출한 뒤에는 `model` segment에 **비즈니스 로직**을 추가할 수 있습니다. * 만료 시간 도달 시 token 갱신 * 일정 시간이 지나면 token 자동 무효화 실제 백엔드 호출은 **User entity의 `api` segment**나 `shared/api`에서 수행하세요. ### 3‑3. Pages / Widgets — 권장하지 않음[](#33pages--widgets권장하지-않음 "해당 헤딩으로 이동") * page, widget layer에 token을 저장하면 전역 의존성이 생기고 다른 slice에서 재사용하기 어려워집니다. * `Shared` 또는 `Entities` 중 한 곳에 token을 저장하는 것을 권장합니다. ## 4. Logout & Token Invalidation[](#4logouttokeninvalidation "해당 헤딩으로 이동") ### 로그아웃과 token 무효화[](#로그아웃과-token-무효화 "해당 헤딩으로 이동") 일반적으로 애플리케이션에는 `로그아웃 전용 페이지`가 없습니다.
그러나 로그아웃 기능은 매우 중요하며 다음 두 단계로 이루어집니다. 1. 백엔드에 인증된 로그아웃 request (예: `POST /logout`) 2. token store reset (access/refresh token 모두 제거) > 모든 API request을 `shared/api`에 모아 관리한다면, 로그아웃 API는 `login()` 근처 (`shared/api/endpoints/logout.ts`)에 배치합니다.
특정 UI(예: Header)에서만 호출된다면 `widgets/header/api/logout.ts` 같이 버튼 근처에 두는 것도 좋습니다. token store reset은 로그아웃 버튼을 가진 UI에서 트리거됩니다.
request와 reset를 widget의 `model` segment에 함께 둘 수도 있습니다. ### 자동 로그아웃[](#자동-로그아웃 "해당 헤딩으로 이동") 다음 두 경우에는 반드시 token store를 초기화하세요. * 로그아웃 request 실패 * 로그인 token 갱신(`/refresh`) 실패 > token을 Entities(User)에 보관한다면 해당 entitle의 `model` segment에서 초기화 코드를 둡니다.
Shared layer라면 `shared/auth` segment로 분리하는 것도 좋습니다. --- # Autocomplete WIP 작성 진행 중 행을 앞당기고 싶다면 다음을 도와주세요: * 📢 의견 공유 [글에 댓글·이모지 달기](https://github.com/feature-sliced/documentation/issues/170) * 💬 자료 모으기 [채팅방에 관련 자료 남기기](https://t.me/feature_sliced) * ⚒️ 기여하기 [다른 방식으로 기여](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* > About decomposition by layers ## See also[](#see-also "해당 헤딩으로 이동") * [(Discussion) About the application of the methodology for the selection with loaded dictionaries](https://github.com/feature-sliced/documentation/discussions/65#discussioncomment-480807) --- # Browser API WIP 작성 진행 중 행을 앞당기고 싶다면 다음을 도와주세요: * 📢 의견 공유 [글에 댓글·이모지 달기](https://github.com/feature-sliced/documentation/issues/197) * 💬 자료 모으기 [채팅방에 관련 자료 남기기](https://t.me/feature_sliced) * ⚒️ 기여하기 [다른 방식으로 기여](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* > About working with the Browser API: localStorage, audio Api, bluetooth API, etc. > > You can ask about the idea in more detail [@alex\_novi](https://t.me/alex_novich) --- # CMS WIP 작성 진행 중 행을 앞당기고 싶다면 다음을 도와주세요: * 📢 의견 공유 [글에 댓글·이모지 달기](https://github.com/feature-sliced/documentation/issues/172) * 💬 자료 모으기 [채팅방에 관련 자료 남기기](https://t.me/feature_sliced) * ⚒️ 기여하기 [다른 방식으로 기여](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* ## Features may be different[](#features-may-be-different "해당 헤딩으로 이동") In some projects, all the functionality is concentrated in data from the server >
*🍰 Stay tuned!* > Errors, Alerts, Notifications, ... --- # i18n WIP 작성 진행 중 행을 앞당기고 싶다면 다음을 도와주세요: * 📢 의견 공유 [글에 댓글·이모지 달기](https://github.com/feature-sliced/documentation/issues/171) * 💬 자료 모으기 [채팅방에 관련 자료 남기기](https://t.me/feature_sliced) * ⚒️ 기여하기 [다른 방식으로 기여](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* ## Where to place it? How to work with this?[](#where-to-place-it-how-to-work-with-this "해당 헤딩으로 이동") *
*🍰 Stay tuned!* > About ways to initialize metrics in the application --- # Monorepositories WIP 작성 진행 중 행을 앞당기고 싶다면 다음을 도와주세요: * 📢 의견 공유 [글에 댓글·이모지 달기](https://github.com/feature-sliced/documentation/issues/221) * 💬 자료 모으기 [채팅방에 관련 자료 남기기](https://t.me/feature_sliced) * ⚒️ 기여하기 [다른 방식으로 기여](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* > About applicability for mono repositories, about bff, about microapps ## See also[](#see-also "해당 헤딩으로 이동") * [(Discussion) About mono repositories and plug-ins-packages](https://github.com/feature-sliced/documentation/discussions/50) * [(Thread) About the application for a mono repository](https://t.me/feature_sliced/2412) --- # Page layouts 여러 페이지에서 **동일한 공통 layout(header, sidebar, footer)** 을 사용하고,
그 안의 **Content 영역**(각 페이지에서 렌더링할 컴포넌트)만 달라질 때 사용하는 *page layout* 개념을 설명합니다. info 더 궁금한 점이 있나요? 페이지 우측의 피드백 버튼을 눌러 의견을 남겨 주세요. 여러분의 제안은 문서 개선에 큰 도움이 됩니다! ## Simple layout[](#simple-layout "해당 헤딩으로 이동") simple layout은 아래 예시에서 볼 수 있습니다.
header, 두 개의 sidebar, 외부 링크(GitHub, Twitter)가 있는 footer로 구성되며, 복잡한 비즈니스 로직은 없습니다. * **정적 요소**: 고정된 menu, logo, footer 등 * **동적 요소**: sidebar toggle, header 오른쪽의 theme switch button 이 Layout 컴포넌트는 `shared/ui` 또는 `app/layouts` 같은 common 폴더에 두고,
`siblingPages`(SiblingPageSidebar)와 `headings`(HeadingsSidebar) props로 sidebar content를 **주입(의존성 주입)** 받아 사용합니다. shared/ui/layout/Layout.tsx ``` import { Link, Outlet } from "react-router-dom"; import { useThemeSwitcher } from "./useThemeSwitcher"; export function Layout({ siblingPages, headings }) { const [theme, toggleTheme] = useThemeSwitcher(); return (
Router의 nesting 기능을 이용하면, 공통된 URL 패턴을 가진 여러 경로(예: /users, /users/profile, /users/settings)를 하나의 `route group` 으로 묶을 수 있습니다. 이렇게 만든 route group에 한 번만 layout을 지정하면, 해당 그룹의 모든 페이지에 동일한 layout이 적용됩니다. 2. **코드 복사 & 붙여넣기**
레이아웃은 자주 변경되지 않으므로, 필요한 페이지만 복사해 두고 수정할 때만 업데이트하세요. 이렇게 하면 다른 페이지에 영향을 주지 않으며, 페이지 간 관계를 주석으로 남겨 누락을 방지할 수 있습니다. 위 방식이 적합하지 않다면, layout에 widget을 포함하는 다음 두 가지 해결책을 검토하세요: 1. **Render Props 또는 Slots 사용하기**
React에서는 [render props](https://www.patterns.dev/react/render-props-pattern/)를, Vue에서는 [slots](https://vuejs.org/guide/components/slots)를 사용해 `부모 layout 컴포넌트에 자식 UI를 props/slot 형태로 전달해 특정 위치에 주입(injection)` 하는 방식입니다. 2. **layout을 App layer로 이동하기**
`app/layouts` 등에 layout 파일을 두고, 필요한 widget을 조합해 사용하세요. ## 참고 자료[](#참고-자료 "해당 헤딩으로 이동") React 및 Remix(React Router와 유사)의 인증 layout 구축에 대한 예시는 [튜토리얼](/documentation/kr/docs/get-started/tutorial.md)에서 확인하실 수 있습니다. --- # Desktop/Touch platforms WIP 작성 진행 중 행을 앞당기고 싶다면 다음을 도와주세요: * 📢 의견 공유 [글에 댓글·이모지 달기](https://github.com/feature-sliced/documentation/issues/198) * 💬 자료 모으기 [채팅방에 관련 자료 남기기](https://t.me/feature_sliced) * ⚒️ 기여하기 [다른 방식으로 기여](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* > About the application of the methodology for desktop/touch --- # SSR WIP 작성 진행 중 행을 앞당기고 싶다면 다음을 도와주세요: * 📢 의견 공유 [글에 댓글·이모지 달기](https://github.com/feature-sliced/documentation/issues/173) * 💬 자료 모으기 [채팅방에 관련 자료 남기기](https://t.me/feature_sliced) * ⚒️ 기여하기 [다른 방식으로 기여](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* > About the implementation of SSR using the methodology --- # Theme WIP 작성 진행 중 행을 앞당기고 싶다면 다음을 도와주세요: * 📢 의견 공유 [글에 댓글·이모지 달기](https://github.com/feature-sliced/documentation/issues/207) * 💬 자료 모으기 [채팅방에 관련 자료 남기기](https://t.me/feature_sliced) * ⚒️ 기여하기 [다른 방식으로 기여](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* ## Where should I put my work with the theme and palette?[](#where-should-i-put-my-work-with-the-theme-and-palette "해당 헤딩으로 이동") >
대표적으로 [`type-fest`](https://github.com/sindresorhus/type-fest)를 설치합니다. 2. **내부 라이브러리 구축**
`shared/lib/utility-types` 폴더를 만들고 README에 “우리 팀에서 유틸리티 타입이라 부르는 기준”과 “추가·제외 규칙”을 명확히 적어 둡니다. > 유틸리티 타입의 **재사용 가능성**을 지나친 기대를 하지 마세요.
재사용 가능하다고 해서 반드시 전역에 둘 필요는 없습니다. 아래처럼 **사용 위치 근처**에 두는 편이 유지보수에 유리할 때가 많습니다. * 📂 pages * 📂 home * 📂 api * 📄 ArrayValues.ts (유틸리티 타입) * 📄 getMemoryUsageMetrics.ts (유틸리티 타입을 사용하는 코드) warning `shared/types` 폴더를 만들거나 각 slice에 `types` segment를 추가하고 싶을 수 있습니다.
그러나 **types 는 코드의 목적을 설명하지 못하는 분류**입니다.
segment와 폴더는 무엇을 담는지가 아니라 왜 존재하는지를 드러내야 합니다. ## 비즈니스 entity와 상호 참조[](#비즈니스entity와-상호-참조 "해당 헤딩으로 이동") 앱에서 가장 핵심이 되는 타입은 **비즈니스 entity**—즉, 도메인 객체—입니다.
음악 스트리밍 서비스를 예로 들면 *Song*, *Album* 등이 entity입니다. ### 1. 백엔드 Response 타입[](#1-백엔드-response-타입 "해당 헤딩으로 이동") 백엔드에서 내려오는 데이터를 먼저 타입으로 정의합니다.
추가적인 타입 안전성을 위해 [Zod](https://zod.dev) 같은 schema 기반 유효성 검사을 적용할 수도 있습니다. shared/api/songs.ts ``` import type { Artist } from "./artists"; interface Song { id: number; title: string; artists: Array
**Request·Response 코드를 Shared에 두면** 이런 상호 참조를 한곳에서 관리할 수 있어 유지보수가 간편해집니다. 반대로 이 함수를 `entities/song/api` 내부에 두면 다음과 같은 문제가 생깁니다. * `entities/artist` slice가 `Song`을 **가져오고 싶어도**
FSD의 [layer별 import 규칙](/documentation/kr/docs/reference/layers.md#import-rule-on-layers) 때문에 **동일 layer 간(import)** 의존은 금지됩니다. * 규칙 요약 > *“한 slice의 모듈은 자신보다 **아래 layer**에 있는 slice만 import할 수 있다.”* 즉, 동일 layer 간 cross-import가 막혀 있어 **Artist → Song** 의존을 직접 연결하기 어렵습니다.
이럴 땐 제네릭 파라미터화 또는 `@x` Public API 같은 방법을 선택해야 합니다. ### 2. 상호 참조 해결 전략[](#2-상호-참조-해결-전략 "해당 헤딩으로 이동") 1. **제네릭 타입 매개변수화**
entity 간 연결이 필요한 타입에는 제네릭 타입 매개변수를 선언하고, 필요한 제약 조건을 부여합니다. 예를 들어, Song 타입에 ArtistType이라는 제약 조건을 설정할 수 있습니다. entities/song/model/song.ts ``` interface Song
FSD에서 entity 간 의존을 허용하려면, 참조 대상 entity 내부에 상대 entity 전용 Public API를 `@x` 디렉터리에 둡니다. 예를 들어 `artist`와 `playlist`가 `song`을 참조해야 한다면 다음과 같이 구성합니다. * 📂 entities * 📂 song * 📂 @x * 📄 artist.ts (artist entity용 public API) * 📄 playlist.ts (playlist entity용 public API) * 📄 index.ts (기본 public API) 파일 `📄 entities/song/@x/artist.ts`의 내용은 `📄 entities/song/index.ts`와 유사합니다: entities/song/@x/artist.ts ``` export type { Song } from "../model/song.ts"; ``` 이제 `📄 entities/artist/model/artist.ts`에서는 다음과 같이 `Song`을 가져옵니다. entities/artist/model/artist.ts ``` import type { Song } from "entities/song/@x/artist"; export interface Artist { name: string; songs: Array
1. 애플리케이션 특성이 없는 제너릭 타입 2. 애플리케이션 전체에 알고 있어야 하는 타입 ### 1) 제너릭 타입[](#1-제너릭-타입 "해당 헤딩으로 이동") 첫 번째 경우에는 관련 타입을 Shared 폴더 안에 적절한 segment로 배치하면 됩니다. 예를 들어, 분석 전역 변수를 위한 Interface가 있다면 `shared/analytics`에 두는 것이 좋습니다. warning `shared/types` 폴더는 만들지 않는 편이 좋습니다. “타입이기 때문”이라는 이유만으로 무관한 항목을 묶으면 코드 검색이 어려워집니다. ### 2) 애플리케이션 Global 타입[](#2-애플리케이션-global-타입 "해당 헤딩으로 이동") `Redux(순수 Redux + RTK 미사용)` 프로젝트에서 자주 나타납니다. 모든 reducer를 합쳐야 store 타입이 완성되지만, 이 타입은 전역에서 selector에 필요합니다. app/store/index.ts ``` import { combineReducers, createStore } from "redux"; import { songReducer } from "entities/song"; import { artistReducer } from "entities/artist"; const rootReducer = combineReducers(songReducer, artistReducer); const store = createStore(rootReducer); type RootState = ReturnType
([Data transfer objects and mappers](#data-transfer-objects-and-mappers) 섹션도 참고하세요.)
특히 백엔드 Response이 schema와 일치하지 않을 때 Request을 실패시키면, 조기에 버그를 발견할 수 있으므로 schema를 `api` segment에 두는 편이 일반적입니다. ## Component props, context 타입[](#componentprops-context타입 "해당 헤딩으로 이동") 일반적으로 `Component·Context 파일과 같은 파일`에 둡니다. 단일 파일(Vue·Svelte 등)에서 여러 Component가 Interface를 공유해야 한다면, 같은 폴더(보통 `ui` segment)에 별도 파일을 만듭니다. pages/home/ui/RecentActions.tsx ``` interface RecentActionsProps { actions: Array<{ id: string; text: string }>; } export function RecentActions({ actions }: RecentActionsProps) { /* … */ } ``` Vue에서 Interface를 별도 파일에 저장한 예는 다음과 같습니다: pages/home/ui/RecentActionsProps.ts ``` export interface RecentActionsProps { actions: Array<{ id: string; text: string }>; } ``` pages/home/ui/RecentActions.vue ``` ``` ## Ambient 선언 파일(\*.d.ts)[](#ambient-선언-파일dts "해당 헤딩으로 이동") [Vite](https://vitejs.dev)나 [ts-reset](https://www.totaltypescript.com/ts-reset) 같은 일부 패키지는 전역 Ambient 선언이 필요합니다. * **단순**하면 `src/`에 두어도 무방 * 구조를 **명확히** 하려면 `app/ambient/`에 배치 타입이 없는 패키지는 `shared/lib/untyped-packages/%LIB%.d.ts`에 직접 선언합니다. ### 타입이 없는 외부 패키지[](#타입이-없는-외부-패키지 "해당 헤딩으로 이동") 타입 정의가 없는 패키지는 **미타입(declare module)으로 선언**하거나 **직접 타입**을 작성해야 합니다.
권장 위치는 `shared/lib/untyped-packages`. 이 폴더에 **`%LIBRARY_NAME%.d.ts`** 파일을 만들고 필요한 타입을 선언합니다. shared/lib/untyped-packages/use-react-screenshot.d.ts ``` // 공식 타입 정의가 없는 라이브러리 예시 declare module "use-react-screenshot"; ``` ## 타입 자동 생성[](#타입-자동-생성 "해당 헤딩으로 이동") 외부 schema(OpenAPI 등)로부터 타입을 생성하는 경우, 전용 디렉터리를 둡니다.
예: `shared/api/openapi` — README에 `파일 용도·재생성 방법`을 기록하면 좋습니다. --- # White Labels WIP 작성 진행 중 행을 앞당기고 싶다면 다음을 도와주세요: * 📢 의견 공유 [글에 댓글·이모지 달기](https://github.com/feature-sliced/documentation/issues/215) * 💬 자료 모으기 [채팅방에 관련 자료 남기기](https://t.me/feature_sliced) * ⚒️ 기여하기 [다른 방식으로 기여](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* > Figma, brand uikit, templates, adaptability to brands ## See also[](#see-also "해당 헤딩으로 이동") * [(Thread) About the application for white-labels (branded) projects](https://t.me/feature_sliced/1543) * [(Presentation) About white-labels apps and design](http://yadi.sk/i/5IdhzsWrpO3v4Q) --- # Cross-import WIP 작성 진행 중 행을 앞당기고 싶다면 다음을 도와주세요: * 📢 의견 공유 [글에 댓글·이모지 달기](https://github.com/feature-sliced/documentation/issues/220) * 💬 자료 모으기 [채팅방에 관련 자료 남기기](https://t.me/feature_sliced) * ⚒️ 기여하기 [다른 방식으로 기여](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* > Cross-import는 Layer나 추상화가 원래의 책임 범위를 넘어설 때 발생합니다. 방법론에서는 이러한 Cross-import를 해결하기 위한 별도의 Layer를 정의합니다. ## 참고 자료[](#참고-자료 "해당 헤딩으로 이동") * [(스레드) Cross-import가 불가피한 상황 논의](https://t.me/feature_sliced/4515) * [(스레드) Entity에서 Cross-import 해결 방법](https://t.me/feature_sliced/3678) * [(스레드) Cross-import와 책임 범위 관계](https://t.me/feature_sliced/3287) * [(스레드) Segment 간 import 이슈 해결](https://t.me/feature_sliced/4021) * [(스레드) Shared 내부 구조의 Cross-import 해결](https://t.me/feature_sliced/3618) --- # Desegmentation WIP 작성 진행 중 행을 앞당기고 싶다면 다음을 도와주세요: * 📢 의견 공유 [글에 댓글·이모지 달기](https://github.com/feature-sliced/documentation/issues/148) * 💬 자료 모으기 [채팅방에 관련 자료 남기기](https://t.me/feature_sliced) * ⚒️ 기여하기 [다른 방식으로 기여](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* ## 상황[](#상황 "해당 헤딩으로 이동") 프로젝트에서 동일한 도메인의 모듈들이 서로 연관되어 있음에도 불구하고, 프로젝트 전체에 불필요하게 분산되어 있는 경우가 많습니다. ``` ├── components/ | ├── DeliveryCard | ├── DeliveryChoice | ├── RegionSelect | ├── UserAvatar ├── actions/ | ├── delivery.js | ├── region.js | ├── user.js ├── epics/ | ├── delivery.js | ├── region.js | ├── user.js ├── constants/ | ├── delivery.js | ├── region.js | ├── user.js ├── helpers/ | ├── delivery.js | ├── region.js | ├── user.js ├── entities/ | ├── delivery/ | | ├── getters.js | | ├── selectors.js | ├── region/ | ├── user/ ``` ## 문제점[](#문제점 "해당 헤딩으로 이동") 이는 높은 응집도 원칙을 위반하며, **Changes Axis의 과도한 확장**을 초래합니다. ## 무시했을 때의 결과[](#무시했을-때의-결과 "해당 헤딩으로 이동") * delivery 관련 로직 수정 시 여러 위치의 코드를 찾아 수정해야 하며, 이는 **Changes Axis를 불필요하게 확장**합니다 * user 관련 로직을 이해하려면 프로젝트 전반의 **actions, epics, constants, entities, components**를 모두 찾아봐야 합니다 * 암묵적 연결로 인해 도메인 영역이 비대해지고 관리가 어려워집니다 * 불필요한 파일들이 쌓여 문제 인식이 어려워집니다 ## 해결 방안[](#해결-방안 "해당 헤딩으로 이동") 도메인이나 use case와 관련된 모듈들을 한 곳에 모아 배치합니다. 이를 통해 모듈 학습이나 수정 시 필요한 모든 요소를 쉽게 찾을 수 있습니다. > 이 접근은 코드베이스의 탐색성과 가독성을 높이고, 모듈 간 관계를 더 명확하게 보여줍니다. ``` - ├── components/ - | ├── DeliveryCard - | ├── DeliveryChoice - | ├── RegionSelect - | ├── UserAvatar - ├── actions/ - | ├── delivery.js - | ├── region.js - | ├── user.js - ├── epics/{...} - ├── constants/{...} - ├── helpers/{...} ├── entities/ | ├── delivery/ + | | ├── ui/ # ~ components/ + | | | ├── card.js + | | | ├── choice.js + | | ├── model/ + | | | ├── actions.js + | | | ├── constants.js + | | | ├── epics.js + | | | ├── getters.js + | | | ├── selectors.js + | | ├── lib/ # ~ helpers | ├── region/ | ├── user/ ``` ## 참고 자료[](#참고-자료 "해당 헤딩으로 이동") * [(아티클) Coupling과 Cohesion의 명확한 이해](https://enterprisecraftsmanship.com/posts/cohesion-coupling-difference/) * [(아티클) Coupling, Cohesion과 Law of Demeter](https://medium.com/german-gorelkin/low-coupling-high-cohesion-d36369fb1be9) --- # Routing WIP 작성 진행 중 행을 앞당기고 싶다면 다음을 도와주세요: * 📢 의견 공유 [글에 댓글·이모지 달기](https://github.com/feature-sliced/documentation/issues/169) * 💬 자료 모으기 [채팅방에 관련 자료 남기기](https://t.me/feature_sliced) * ⚒️ 기여하기 [다른 방식으로 기여](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* ## 상황[](#상황 "해당 헤딩으로 이동") Page의 URL이 하위 Layer에 하드코딩되어 있는 경우가 있습니다. entities/post/card ```
모든 프로젝트가 새로운 아키텍처를 요구하는 것은 아닙니다. ### 전환을 고려해야 할 징후[](#전환을-고려해야-할-징후 "해당 헤딩으로 이동") 1. 신규 팀원이 프로젝트에 적응하기 어려워하는 경우 2. 코드 일부를 수정할 때, 관련 없는 다른 코드에 오류가 발생하는 경우가 **잦은** 경우 3. 새 기능을 추가할 때 고려해야 할 사항이 너무 많아 어려움을 겪는 경우 **팀의 합의 없이 FSD 전환을 시작하지 마세요.**
팀 리더라도 전환의 이점이 학습·전환 비용을 상회한다는 점을 먼저 설득해야 합니다.
또한, 개선 효과가 바로 눈에 띄지 않을 수 있으므로 **팀원** 및 **프로젝트 매니저(PM)** 의 승인을 사전에 확보하고 이점을 공유하세요. PM 설득 시 고려할 사항 * FSD 전환은 단계적으로 진행할 수 있어 기존 기능 개발을 중단하지 않아도 됩니다. * 명확한 아키텍처 구조는 신규 개발자 온보딩 시간을 단축합니다. * 공식 문서를 활용하면 별도 문서 유지·관리 비용을 절감할 수 있습니다. *** 마이그레이션을 시작하기로 결정했다면, `📁 src` 폴더에 별칭(alias)을 설정하는 것을 첫 단계로 삼으세요.
## 1단계: 페이지 단위로 코드 분리하기[](#divide-code-by-pages "해당 헤딩으로 이동") 대부분의 커스텀 아키텍처는 규모와 관계없이 이미 어느 정도 페이지 단위로 코드를 나누고 있습니다. `📁 pages` 폴더가 있다면 이 단계를 건너뛰어도 됩니다. 위에 예시 폴더처럼 `📁 routes`만 있다면 다음 순서를 따르세요. 1. `📁 pages` 폴더를 새로 만듭니다. 2. `📁 routes`에 있던 **페이지용 컴포넌트**를 가능한 한 모두 `📁 pages` 폴더로 옮깁니다. 3. 코드를 옮길 때마다 해당 페이지 전용 폴더를 만들고 그 안에 `index` 파일을 추가해 entry를 노출합니다. note 이 단계에서는 **Page A에서 Page B의 코드를 import**해도 괜찮습니다. 나중 단계에서 이러한 의존성을 분리할 예정이니, 우선 **페이지 폴더를 만드는 것**에 집중하세요. route file: src/routes/products.\[id].js ``` export { ProductPage as default } from "src/pages/product" ``` page index file: src/pages/product/index.js ``` export { ProductPage } from "./ProductPage.jsx" ``` page component file: src/pages/product/ProductPage.jsx ``` export function ProductPage(props) { return ; } ``` ## 2단계: 페이지 외부 코드를 분리하기[](#separate-everything-else-from-pages "해당 헤딩으로 이동") 1. **`📁 src/shared` 폴더를 만든다.** * `📁 pages` 또는 `📁 routes`를 **import하지 않는** 모든 코드를 이곳으로 이동한다. 2. **`📁 src/app` 폴더를 만든다.** * `📁 pages` 또는 `📁 routes`를 **import하는** 코드를 이곳으로 옮긴다. 라우트 파일도 여기에 포함한다. > **Shared layer에는 slice가 없다.**
따라서 segment 간 import는 자유롭다. 이제 폴더 구조는 다음과 같아야 합니다: 📁 src * 📁 app * 📁 routes * 📄 products.jsx * 📄 products.\[id].jsx * 📄 App.jsx * 📄 index.js * 📁 pages * 📁 product * 📁 ui * 📄 ProductPage.jsx * 📄 index.js * 📁 catalog * 📁 shared * 📁 actions * 📁 api * 📁 components * 📁 containers * 📁 constants * 📁 i18n * 📁 modules * 📁 helpers * 📁 utils * 📁 reducers * 📁 selectors * 📁 styles ## 3단계: 페이지 간의 cross-imports 해결[](#tackle-cross-imports-between-pages "해당 헤딩으로 이동") 한 페이지가 다른 페이지의 코드를 가져오고 있다면 두 가지 방법으로 의존성을 제거한다. | 방법 | 사용 시점 | | -------------------- | ------------------------------------------------------------ | | **A. 코드 복사** | 페이지마다 로직이 달라질 가능성이 있거나, 재사용성이 낮을 때 | | **B. Shared로 이동** | 여러 페이지에서 공통으로 쓰일 때 | * Shared 이동 위치 예시 * UI 구성 요소 → `📁 shared/ui` * 설정 상수 → `📁 shared/config` * 백엔드 호출 → `📁 shared/api` note 코드 복사는 잘못이 아니다. **중복보다 의존성 최소화**가 더 중요할 때가 많다.
다만 비즈니스 로직은 중복을 피해야 하며, 복사 시에도 DRY 원칙을 염두에 둔다. ## 4단계: Shared 레이어 정리하기[](#unpack-shared-layer "해당 헤딩으로 이동") * **한 페이지에서만 쓰이는 코드**는 해당 페이지 **slice**로 이동한다. * `actions / reducers / selectors`도 예외가 아니다. **사용처와 가까이** 두는 편이 좋다. Shared는 모든 layer가 의존할 수 있는 **공통 의존점**이므로, 코드를 최소화해 변경 위험을 낮춘다. 최종 폴더 구조는 다음과 같아야 합니다: 📁 src * 📁 app (unchanged) * 📁 pages * 📁 product * 📁 actions * 📁 reducers * 📁 selectors * 📁 ui * 📄 Component.jsx * 📄 Container.jsx * 📄 ProductPage.jsx * 📄 index.js * 📁 catalog * 📁 shared (only objects that are reused) * 📁 actions * 📁 api * 📁 components * 📁 containers * 📁 constants * 📁 i18n * 📁 modules * 📁 helpers * 📁 utils * 📁 reducers * 📁 selectors * 📁 styles ## 5단계: 기술적 목적별 segment 정리[](#organize-by-technical-purpose "해당 헤딩으로 이동") | segment | 용도 예시 | | -------- | ---------------------------------- | | `ui` | Components, formatters, styles | | `api` | Backend requests, DTOs, mappers | | `model` | Store, schema, business logic | | `lib` | Shared utilities / helpers | | `config` | Configuration files, feature flags | > “**무엇인지**”가 아니라 “**무엇을 위해**” 존재하는지를 기준으로 나눈다.
따라서 `components`, `utils`, `types` 같은 이름은 지양한다. 1. **각 페이지**에 `ui / model / api` 등 필요한 segment를 만든다. 2. **Shared** 폴더를 정리한다. * `components·containers` → `shared/ui` * `helpers·utils` → `shared/lib` (기능별 그룹화 후) * `constants` → `shared/config` ## 선택 단계[](#optional-steps "해당 헤딩으로 이동") ### 6단계: 여러 페이지에서 재사용되는 Redux slice를 Entities / Features layer로 분리하기[](#form-entities-features-from-redux "해당 헤딩으로 이동") * 여러 페이지에서 재사용되는 Redux **slice**는 주로 **product, user** 같은 **business entity**를 표현합니다.
이 경우 **Entities layer**로 옮기고, **entity**마다 폴더를 하나씩 만듭니다. * 댓글 작성처럼 **사용자 행동(action)** 을 다루는 **slice**는 **Features layer**로 이동합니다. **Entities**와 **Features**는 서로 독립적으로 사용될 수 있도록 설계되어 있습니다.
Entitles 간 연결이 필요하면 [Business-Entities Cross-Relations 가이드](/documentation/kr/docs/guides/examples/types.md#business-entities-and-their-cross-references)를 참고하세요.
해당 **slice**와 연관된 API 함수는 `📁 shared/api`에 그대로 두어도 무방합니다. ### 7단계: modules 폴더 리팩터링[](#refactor-your-modules "해당 헤딩으로 이동") `📁 modules`는 과거에 비즈니스 로직을 모아 두던 곳으로, 성격상 **Features layer**와 비슷합니다.
단, 앱 Header처럼 **large UI block**(예: global Header, Sidebar)이라면 **Widgets layer**로 옮기는 편이 좋습니다. ### 8단계: shared/ui에 presentational UI 기반 마련하기[](#form-clean-ui-foundation "해당 헤딩으로 이동") `📁 shared/ui`에는 비즈니스 로직이 전혀 없는, 재사용 가능한 presentational UI 컴포넌트만 남겨야 합니다. * 기존 `📁 components` · `📁 containers`에 있던 컴포넌트에서 비즈니스 로직을 분리해 상위 layer로 이동합니다. * 여러 곳에서 쓰이지 않는 부분은 **복사(paste)** 해서 각 layer에서 독립적으로 관리해도 괜찮습니다. ## 참고 자료[](#see-also "해당 헤딩으로 이동") * [(러시아어 영상) Ilya Klimov — "끝없는 리팩터링의 악순환에서 벗어나기: 기술 부채가 동기와 제품에 미치는 영향](https://youtu.be/aOiJ3k2UvO4) --- # v1 -> v2 마이그레이션 가이드 ## v2 도입 배경[](#v2-도입-배경 "해당 헤딩으로 이동") **feature-slices** 개념은 2018년 [첫 발표](https://t.me/feature_slices)된 이후, 다양한 프로젝트 경험과 커뮤니티 피드백을 거치며 발전해 왔습니다.
동시에 **[기본 원칙](https://feature-sliced.github.io/featureslices.dev/v1.0.html)**(표준화된 프로젝트 구조, 비즈니스 로직 우선 분리, isolated features, Public API)은 그대로 유지되었습니다. 하지만 v1에는 다음과 같은 한계가 있었습니다: * 과도한 **boilerplate** 발생 * 추상화 규칙이 모호해 **코드베이스 복잡도** 상승 * 암묵적 설계로 **확장·온보딩 어려움** 이러한 한계를 해결하기 위해 ([`v2`](https://github.com/feature-sliced/documentation))는 기존 장점을 유지하면서도 위 과제들을 보완하도록 설계되었습니다.
또한 [Oleg Isonen](https://github.com/kof)이 발표한 [**feature-driven**](https://github.com/feature-sliced/documentation/tree/rc/feature-driven) 등 유사 방법론과 아이디어를 융합해 애플리케이션 구조를 한층 더 **유연**, **명확**, **효율적**으로 다듬었습니다. > 이 과정에서 방법론의 공식 명칭은 *feature-slice*에서 **feature-sliced**로 정식화되었습니다. ## v2 마이그레이션 이유[](#v2-마이그레이션-이유 "해당 헤딩으로 이동") > `WIP:` 작업이 진행 중이며, 일부 세부 사항이 변경될 수 있습니다. ### 직관적 구조 제공[](#직관적-구조-제공 "해당 헤딩으로 이동") v2는 **layer → slice → segment** 3단계만 알면 대부분 구조 결정을 내릴 수 있습니다.
덕분에 새로운 팀원이 **어디에 무엇을 둬야 하나** 부터 고민하지 않아 온보딩 속도가 빨라집니다. ### 유연한 모듈화[](#유연한-모듈화 "해당 헤딩으로 이동") * **독립 영역**은 slice 단위로, **전역 흐름**은 Processes layer로 분리해 확장성을 확보합니다. * 새 module을 추가할 때 *(layer → slice → segment)* 규칙만 따르면 폴더 재배치와 리팩터링 작업 부담이 크게 줄어듭니다. #### 커뮤니티·도구 지원 확대[](#커뮤니티도구-지원-확대 "해당 헤딩으로 이동") v2 개발은 **코어 팀**과 커뮤니티 기여자들이 함께 이끌고 있습니다. 다음 리소스를 활용해 보세요: * **실제 사례 공유**: 다양한 프로젝트 환경에서의 적용 사례 * **단계별 가이드**: 설정·구성·운영 전 과정을 담은 튜토리얼 * **코드 템플릿 & 예제**: 시작부터 배포까지 참고할 수 있는 실전 코드 * **온보딩 문서**: 신규 개발자를 위한 개념 요약 및 학습 자료 * **검증 툴킷**: steiger CLI 등 정책 준수·lint를 지원하는 유틸리티 > v1 지원은 계속 유지되지만, 새로운 기능·개선 사항은 **v2**에 우선 반영됩니다.
주요 업데이트 시에도 **안정적 마이그레이션 경로**를 보장합니다. ## 주요 변경 사항[](#주요-변경-사항 "해당 헤딩으로 이동") ### Layer 구조 명확화[](#layer-구조-명확화 "해당 헤딩으로 이동") v2에서는 layer를 최상위부터 최하위까지 명시적으로 구분합니다: * `/app` > `/processes` > **`/pages`** > **`/features`** > `/entities` > `/shared` * 모든 모듈이 `pages`/`features` layer에만 속하지 않습니다. * 이 구조를 통해 [layer별 의존 규칙](https://t.me/atomicdesign/18708)을 명시적으로 설정할 수 있습니다. * **상위 layer**는 더 넓은 **Context**를 제공합니다. * 상위 layer 모듈은 **하위 layer** 모듈만 import할 수 있습니다. * **하위 layer**는 **변경 리스크(Risk)와 책임(Responsibility)** 이 더 큽니다. * 재사용 빈도가 높아, 수정 시 영향 범위가 넓습니다. ### Shared 통합[](#shared-통합 "해당 헤딩으로 이동") 프로젝트 `src` 루트에 흩어져 있던 UI, lib, API 인프라 추상화를 `/src/shared` 폴더로 통합했습니다. * `shared/ui` - 공통 UI components(선택 사항) * *기존 `Atomic Design` 사용도 가능합니다.* * `shared/lib` - 재사용 가능한 helper libraries * *무분별한 helper dump 지양* * `shared/api` - API entry points * *각 feature/page 내 local 정의 가능하지만, 전역 entry point 집중을 권장* * `shared` 폴더에는 **business logic** 의존을 두지 않습니다 * *불가피할 경우 `entities` layer 이상으로 로직을 옮기세요.* ### Entities / Processes Layer 추가[](#entities--processes-layer-추가 "해당 헤딩으로 이동") v2에서는 로직 복잡성과 높은 결합을 줄이기 위한 **새로운 추상화**가 추가되었습니다. * **`/entities`**
프론트엔드에서 사용되는 **business entities**(예: `user`, `order`, `i18n`, `blog`)를 담당하는 layer입니다. * **`/processes`**
애플리케이션 전반에 걸친 **비즈니스 process**(예: `payment`, `auth`, `quick-tour`)를 캡슐화하는 선택적 layer입니다.
process *로직이 여러 페이지에 분산될 때* 도입을 권장합니다. ### 추상화·네이밍 가이드[](#추상화네이밍-가이드 "해당 헤딩으로 이동") 아래에서는 v2 권장 layer·segment 명칭을 이전 명칭과 대응하여 정리했습니다.
추상화·네이밍 관련 상세 가이드는 [명확한 네이밍 권장사항](/documentation/kr/docs/about/understanding/naming.md)을 참고하세요. #### Layer[](#layer "해당 헤딩으로 이동") * `/app` — **Application init** * *이전 명칭: `app`, `core`,`init`, `src/index` (가끔 사용됨)* * `/processes` — [**Business process**](https://github.com/feature-sliced/documentation/discussions/20) * *이전 명칭: `processes`, `flows`, `workflows`* * `/pages` — **Application page** * *이전 명칭: `pages`, `screens`, `views`, `layouts`, `components`, `containers`* * `/features` — [**Feature module**](https://github.com/feature-sliced/documentation/discussions/23) * *이전 명칭: `features`, `components`, `containers`* * `/entities` — [**Business entity**](https://github.com/feature-sliced/documentation/discussions/18#discussioncomment-422649) * *이전 명칭: `entities`, `models`, `shared`* * `/shared` — [**Infrastructure**](https://github.com/feature-sliced/documentation/discussions/31#discussioncomment-453020) 🔥 * *이전 명칭: `shared`, `common`, `lib`* #### Segment[](#segment "해당 헤딩으로 이동") * `/ui` — [**UI segment**](https://github.com/feature-sliced/documentation/discussions/31#discussioncomment-453132) 🔥 * *이전 명칭: `ui`, `components`, `view`* * `/model` — [**비즈니스 로직 segment**](https://github.com/feature-sliced/documentation/discussions/31#discussioncomment-472645) 🔥 * *이전 명칭: `model`, `store`, `state`, `services`, `controller`* * `/lib` — **보조 코드 segment** * *이전 명칭: `lib`, `libs`, `utils`, `helpers`* * `/api` — [**API segment**](https://github.com/feature-sliced/documentation/discussions/66) * *이전 명칭: `api`, `service`, `requests`, `queries`* * `/config` — **애플리케이션 설정 segment** * *이전 명칭: `config`, `env`, `get-env`* ## 낮은 결합 원칙 강화[](#낮은-결합-원칙-강화 "해당 헤딩으로 이동") 새 layer 규칙 덕분에 [Zero-Coupling, High-Cohesion 원칙](/documentation/kr/docs/reference/slices-segments.md#zero-coupling-high-cohesion)을 지키기 쉬워졌습니다. *단, 모듈을 완전히 분리할 수 없는 경우에는 Public API 등 명확한 인터페이스 경계를 정의하고, 해당 의존 코드는 가능한 한 하위 layer에 위치시키는 것을 권장합니다.* ## 참고 자료[](#참고-자료 "해당 헤딩으로 이동") * [React SPB Meetup #1 발표 노트](https://t.me/feature_slices) * [React Berlin Talk - Oleg Isonen Feature Driven Architecture](https://www.youtube.com/watch?v=BWAeYuWFHhs) * [v1↔v2 구조 비교(텔레그램)](https://t.me/feature_sliced/493) * [v2에 대한 새로운 아이디어와 설명 (atomicdesign 채팅)](https://t.me/atomicdesign/18708) * [v2 추상화·네이밍 공식 논의](https://github.com/feature-sliced/documentation/discussions/31) --- # v2.0 -> v2.1 마이그레이션 가이드 v2.1의 핵심 변화는 Page 중심(Page-First) 접근 방식을 통한 인터페이스 구조화입니다. ## v2.0 접근 방식[](#v20-접근-방식 "해당 헤딩으로 이동") v2.0에서는 **Entity** 와 **Feature** 단위를 중심으로 애플리케이션을 분리했습니다.
화면을 이루는 최소 단위인 entity 표현이나 상호작용 요소까지 모두 세분화한 뒤,
이를 **Widget** 으로 조합하고, 최종적으로 **Page** 를 구성하는 모델이었죠. 이렇게 하면 재사용성과 모듈화 면에서 이점이 있었지만,
실제로는 대부분의 비즈니스 로직이 entity·feature layer에 집중되고,
Page는 단순 조합 계층에 머물러 자신만의 책임이 희미해지는 문제가 발생했습니다. ## v2.1 접근 방식[](#v21-접근-방식 "해당 헤딩으로 이동") v2.1에서는 **Pages-First** 사고방식을 도입합니다.
대부분의 개발자가 이미 애플리케이션을 Page 단위로 나누는 데 익숙하고,
코드베이스에서 컴포넌트를 찾을 때도 Page가 자연스러운 출발점이기 때문입니다. * **Page 내부에 주요 UI와 비즈니스 로직**을 두고 **Shared** layer는 순수 재사용 요소만 관리 * 공통 로직이 실제로 여러 Page에서 쓰일 때만 하위 layer(Feature·Entity)로 분리 이 접근의 장점은 다음과 같습니다: 1. **Page가 책임 단위**가 되어, 코드 위치와 역할이 명확해집니다. 2. Shared layer는 **유틸·컴포넌트**처럼 순수 재사용 코드만 담아, 의존 경로가 간결해집니다. 3. 공통 로직을 실제로 재사용할 때만 하위 layer로 이동해, 불필요한 추상화와 의존성 얽힘을 방지합니다. 또한 v2.1에서는 **Entity 간 cross-import**를 `@x` 표기법으로 **표준화**했습니다.
이제 다음과 같은 형식으로 명확한 경로를 사용할 수 있습니다: ## 마이그레이션 프로세스[](#how-to-migrate "해당 헤딩으로 이동") v2.1은 하위 호환성을 보장하므로, 기존 FSD v2.0 프로젝트는 **수정 없이** 동작합니다.
새 모델을 활용하려면 아래 단계를 단계적으로 적용해 보세요. ### 1. Slice 병합[](#1-slice-병합 "해당 헤딩으로 이동") FSD v2.1의 Page-First 모델에서는 **실제로 여러 Page에서 재사용되지 않는** slice를 굳이 독립 단위로 유지할 필요가 없습니다.
단일 page에서만 사용되는 slice는 해당 page 안으로 병합하면, 코드 탐색과 유지보수가 더 쉬워집니다. #### Steiger로 자동 탐지하기[](#steiger로-자동-탐지하기 "해당 헤딩으로 이동") 프로젝트 루트에서 [Steiger](https://github.com/feature-sliced/steiger) linter를 실행하세요.
v2.1 mental model에 맞춘 주요 lint 규칙은 다음과 같습니다: * [`insignificant-slice`](https://github.com/feature-sliced/steiger/tree/master/packages/steiger-plugin-fsd/src/insignificant-slice)
단일 Page에서만 참조되는 slice를 찾아냅니다.
→ **해당 slice를 Page 내부로 병합**하도록 제안합니다. * [`excessive-slicing`](https://github.com/feature-sliced/steiger/tree/master/packages/steiger-plugin-fsd/src/excessive-slicing)
너무 잘게 나뉜 slice를 감지합니다.
→ **유사한 slice를 통합**하거나 **그룹화**해 탐색성을 높이도록 권장합니다. ``` npx steiger src ``` 이 명령으로 `한 번만 쓰이는 slice` 목록이 출력됩니다.
이제 각 slice의 재사용 여부를 검토하고, 과하다면 해당 page로 병합하거나 비슷한 역할끼리 묶어 보세요. Slice 관리 각 계층은 해당 계층에 속한 모든 Slices의 namespace를 관리합니다. 이는 전역 변수를 관리하는 것과 비슷한 개념입니다: * 전역 변수는 꼭 필요한 경우에만 사용하듯이 Slice도 실제로 재사용되는 경우에만 독립적으로 분리하세요 * 한 곳에서만 사용되는 코드는 해당 Page나 Feature 내부로 이동하는 것이 좋습니다 ### 2. Cross Import 표준화[](#2-cross-import-표준화 "해당 헤딩으로 이동") 새로운 `@x-` 표기법으로 Entity 간 cross-import를 통일합니다: entities/B/some/file.ts ``` // v2.1 권장 cross-import 방식 import type { EntityA } from "entities/A/@x/B"; ``` 자세한 내용은 [Public API for cross-imports](/documentation/kr/docs/reference/public-api.md#public-api-for-cross-imports) 문서를 참고하세요. --- # Electron와 함께 사용하기 Electron 애플리케이션은 역할이 다른 여러 **프로세스**(Main, Renderer, Preload)로 구성됩니다.
따라서 FSD를 적용하려면 Electron 특성에 맞게 구조를 조정해야 합니다. ``` └── src ├── app # Common app layer │ ├── main # Main process │ │ └── index.ts # Main process entry point │ ├── preload # Preload script and Context Bridge │ │ └── index.ts # Preload entry point │ └── renderer # Renderer process │ └── index.html # Renderer process entry point ├── main │ ├── features │ │ └── user │ │ └── ipc │ │ ├── get-user.ts │ │ └── send-user.ts │ ├── entities │ └── shared ├── renderer │ ├── pages │ │ ├── settings │ │ │ ├── ipc │ │ │ │ ├── get-user.ts │ │ │ │ └── save-user.ts │ │ │ ├── ui │ │ │ │ └── user.tsx │ │ │ └── index.ts │ │ └── home │ │ ├── ui │ │ │ └── home.tsx │ │ └── index.ts │ ├── widgets │ ├── features │ ├── entities │ └── shared └── shared # Common code between main and renderer └── ipc # IPC description (event names, contracts) ``` ## Public API 규칙[](#public-api-규칙 "해당 헤딩으로 이동") * 각 프로세스는 자신만의 Public API를 가져야 합니다. * 예) `renderer` 코드가 `main` 폴더 모듈을 직접 import 하면 안 됩니다. * 단, `src/shared` 폴더는 두 프로세스 모두에게 공개됩니다. * (프로세스 간 통신 계약과 타입 정의를 위해 필요합니다) ## 표준 구조의 추가 변경 사항[](#표준-구조의-추가-변경-사항 "해당 헤딩으로 이동") * **`ipc` segment**를 새로 만들어, 프로세스 간 통신(채널, 핸들러)을 한곳에 모읍니다. * `src/main`에는 이름 그대로 **`pages`, `widgets` layer를 두지 않습니다.**
대신 `features`, `entities`, `shared`만 사용합니다. * `src/app` layer는 **Main, Renderer entry**와 **IPC initialization code**만 담는 전용 영역입니다. * `app` layer 내부의 각 segment는 서로 **교차 의존**이 발생하지 않도록 구성하는 것이 좋습니다. ## Interaction example[](#interaction-example "해당 헤딩으로 이동") src/shared/ipc/channels.ts ``` export const CHANNELS = { GET_USER_DATA: 'GET_USER_DATA', SAVE_USER: 'SAVE_USER', } as const; export type TChannelKeys = keyof typeof CHANNELS; ``` src/shared/ipc/events.ts ``` import { CHANNELS } from './channels'; export interface IEvents { [CHANNELS.GET_USER_DATA]: { args: void, response?: { name: string; email: string; }; }; [CHANNELS.SAVE_USER]: { args: { name: string; }; response: void; }; } ``` src/shared/ipc/preload.ts ``` import { CHANNELS } from './channels'; import type { IEvents } from './events'; type TOptionalArgs
그러나 이 방식은 FSD에서 권장하는 **평탄(flat)한 slice 구조**와 맞지 않아 충돌이 발생합니다. ### NextJS `pages` 폴더를 Project Root로 이동 (권장)[](#nextjs-pages-폴더를-project-root로-이동-권장 "해당 헤딩으로 이동") `pages` 폴더를 **프로젝트 최상위**로 옮긴 뒤,
FSD `src/pages`의 각 페이지 컴포넌트를 `pages` 폴더에서 **re-export** 하면 NextJS 라우팅과 FSD 구조를 모두 유지할 수 있습니다. ``` ├── pages # NextJS 라우팅 폴더 (FSD pages를 재-export) │ └── index.tsx │ └── about.tsx ├── src │ ├── app │ ├── entities │ ├── features │ ├── pages # FSD pages layer │ ├── shared │ └── widgets ``` ### FSD pages layer 이름 변경[](#fsd-pages-layer-이름-변경 "해당 헤딩으로 이동") FSD의 `pages` layer 이름을 변경해 NextJS `pages` 폴더와 충돌을 방지할 수 있습니다.
예를 들어, `pages`를 `views`로 바꾸면 라우팅 폴더와 FSD 페이지 layer를 동시에 사용할 수 있습니다. ``` ├── app ├── entities ├── features ├── pages # NextJS 라우팅 폴더 ├── views # 변경된 FSD pages layer ├── shared ├── widgets ``` 폴더 이름을 변경했다면 프로젝트 README나 내부 문서에 반드시 기록해야 합니다.
이 내용을 [프로젝트 지식](/documentation/kr/docs/about/understanding/knowledge-types.md)에 포함해 팀원들이 쉽게 확인할 수 있도록 하세요. ## NextJS에서 `app` layer 구현하기[](#app-absence "해당 헤딩으로 이동") NextJS 13 이전 버전에는 FSD app layer에 대응하는 전용 폴더가 없습니다.
대신 pages/\_app.tsx가 모든 페이지의 wrapping component로 작동합니다.
이 파일에서 전역 상태 관리(global state management)와 레이아웃 구성(layout)을 담당합니다. ### `pages/_app.tsx`에 app layer 기능 통합하기[](#pages_apptsx에-app-layer-기능-통합하기 "해당 헤딩으로 이동") 먼저 `src/app/providers/index.tsx`에 `App` 컴포넌트를 정의합니다.
이 컴포넌트에서 전체 애플리케이션의 provider와 layout을 설정합니다. ``` // app/providers/index.tsx const App = ({ Component, pageProps }: AppProps) => { return (
이 과정에서 global style도 함께 import할 수 있습니다. ``` // pages/_app.tsx import 'app/styles/index.scss' export { default } from 'app/providers'; ``` ## App Router 사용하기[](#app-router "해당 헤딩으로 이동") NextJS 13.4부터 `app` 폴더 기반 App Router를 지원합니다.
FSD 아키텍처를 App Router와 함께 사용하려면 다음 구조를 적용하세요. `app` 폴더는 NextJS App Router 전용입니다.
`src/app`은 FSD의 app layer를 유지합니다. 필요에 따라 App Router와 Pages Router를 함께 사용할 수 있습니다. ``` ├── app # NextJS의 App Router용 폴더 ├── pages # NextJS의 Pages Router용 폴더 (선택적) │ ├── README.md # 폴더의 용도 설명 ├── src │ ├── app # FSD의 app layer │ ├── entities │ ├── features │ ├── pages # FSD의 pages layer │ ├── shared │ ├── widgets ``` `app` 폴더에서 `src/pages`의 컴포넌트를 re-export하세요.
App Router만 사용해도 `Pages Router`와의 호환성을 위해 `root pages` 폴더를 유지합니다. [](https://stackblitz.com/edit/stackblitz-starters-aiez55?file=README.md) ## Middleware[](#middleware "해당 헤딩으로 이동") NextJS middleware 파일은 반드시 프로젝트 root 폴더(`app` 또는 `pages` 폴더와 동일 수준)에 둬야 합니다.
`src` 아래에 두면 NextJS가 인식하지 않으므로, middleware 파일을 root로 이동하세요. ## 참고 자료[](#see-also "해당 헤딩으로 이동") * [(스레드) NextJS의 pages 폴더에 대한 토론](https://t.me/feature_sliced/3623) --- # NuxtJS와 함께 사용하기 NuxtJS 프로젝트에 FSD(Feature-Sliced Design)를 도입할 때는 기본 구조와 FSD 원칙 간에 다음과 같은 차이를 고려해야 합니다: * NuxtJS는 `src` 폴더 없이 project root에서 파일을 관리합니다. * NuxtJS는 `pages` 폴더 기반 파일 라우팅을 사용하지만, FSD는 slice 관점에서 폴더를 구성합니다. ## `src` 폴더 alias 설정하기[](#src-폴더-alias-설정하기 "해당 헤딩으로 이동") NuxtJS 프로젝트에도 `src` 폴더를 두고 싶다면, `nuxt.config.ts`의 `alias`에 매핑을 추가하세요. nuxt.config.ts ``` export default defineNuxtConfig({ devtools: { enabled: true }, // 개발 도구 활성화(선택 사항) alias: { "@": '../src' // root의 src 폴더를 @로 참조 }, }) ``` ## 라우터 설정 방법 선택하기[](#라우터-설정-방법-선택하기 "해당 헤딩으로 이동") NuxtJS에서는 두 가지 라우팅 방식을 지원합니다: * **파일 기반 라우팅**: `src/app/routes` 폴더 내 `.vue` 파일을 자동으로 라우트로 등록 * **설정 기반 라우팅**: `src/app/router.options.ts`에서 라우트를 직접 정의 ### 설정 기반 라우팅[](#설정-기반-라우팅 "해당 헤딩으로 이동") `src/app/router.options.ts` 파일을 생성한 뒤, 아래와 같이 `RouterConfig`를 정의하세요: app/router.options.ts ``` import type { RouterConfig } from '@nuxt/schema'; export default
`src/entities/{entity}/api` 폴더에 관련 코드를 모아두세요: ``` └── src/ # ├── app/ # | ... # ├── pages/ # | ... # ├── entities/ # | ├── {entity}/ # | ... └── api/ # | ├── `{entity}.query` # Query Keys와 Query Functions | ├── `get-{entity}` # entity fetch 함수 | ├── `create-{entity}` # entity create 함수 | ├── `update-{entity}` # entity update 함수 | ├── `delete-{entity}` # entity delete 함수 | ... # | # ├── features/ # | ... # ├── widgets/ # | ... # └── shared/ # ... # ``` entities 간에 데이터를 참조해야 하면 [공용 Public API](/documentation/kr/docs/reference/public-api.md#public-api-for-cross-imports)를 사용하거나,
아래 예시처럼 `shared/api/queries`에 모아두는 방법도 있습니다. ### 대안 — shared에 모아두기[](#대안--shared에-모아두기 "해당 헤딩으로 이동") entity별 분리가 어려울 때는 예시 처럼 `src/shared/api/queries`에 Query Factory를 정의하세요. ``` └── src/ # ... # └── shared/ # ├── api/ # ... ├── `queries` # Query Factories | ├── `document.ts` # | ├── `background-jobs.ts` # | ... # └── index.ts # ``` 이후 `@/shared/api/index.ts`에서 다음과 같이 사용합니다: @/shared/api/index.ts ``` export { documentQueries } from "./queries/document"; ``` ## Mutation 배치 문제[](#mutation-배치-문제 "해당 헤딩으로 이동") Query와 Mutation을 같은 위치에 두는 것은 권장하지 않습니다.
두 가지 방안을 제안합니다: ### 사용 위치 근처 api 폴더에 Custom Hook 정의[](#사용-위치-근처-api-폴더에-custom-hook-정의 "해당 헤딩으로 이동") @/features/update-post/api/use-update-title.ts ``` export const useUpdateTitle = () => { const queryClient = useQueryClient(); return useMutation({ mutationFn: ({ id, newTitle }) => apiClient .patch(`/posts/${id}`, { title: newTitle }) .then((data) => console.log(data)), onSuccess: (newPost) => { queryClient.setQueryData(postsQueries.ids(id), newPost); }, }); }; ``` ### entities 또는 shared에 함수만 정의하고, 컴포넌트에서 `useMutation` 사용[](#entities-또는-shared에-함수만-정의하고-컴포넌트에서-usemutation-사용 "해당 헤딩으로 이동") ``` const { mutateAsync, isPending } = useMutation({ mutationFn: postApi.createPost, }); ``` @/pages/post-create/ui/post-create-page.tsx ``` export const CreatePost = () => { const { classes } = useStyles(); const [title, setTitle] = useState(""); const { mutate, isPending } = useMutation({ mutationFn: postApi.createPost, }); const handleChange = (e: ChangeEvent
다음 예시처럼 객체로 정의하세요: ``` const keyFactory = { all: () => ["entity"], lists: () => [...postQueries.all(), "list"], }; ``` info TanStack Query v5의 `queryOptions` 유틸을 사용하면 타입 안전성과 향후 호환성을 높일 수 있습니다. ``` queryOptions({ queryKey, ...options, }); ``` 자세한 내용은 [Query Options API](https://tkdodo.eu/blog/the-query-options-api#queryoptions)에서 확인하세요. ### Query Factory 생성 예시[](#query-factory-생성-예시 "해당 헤딩으로 이동") @/entities/post/api/post.queries.ts ``` import { keepPreviousData, queryOptions } from "@tanstack/react-query"; import { getPosts } from "./get-posts"; import { getDetailPost } from "./get-detail-post"; import { PostDetailQuery } from "./query/post.query"; export const postQueries = { all: () => ["posts"], lists: () => [...postQueries.all(), "list"], list: (page: number, limit: number) => queryOptions({ queryKey: [...postQueries.lists(), page, limit], queryFn: () => getPosts(page, limit), placeholderData: keepPreviousData, }), details: () => [...postQueries.all(), "detail"], detail: (query?: PostDetailQuery) => queryOptions({ queryKey: [...postQueries.details(), query?.id], queryFn: () => getDetailPost({ id: query?.id }), staleTime: 5000, }), }; ``` ### 애플리케이션 코드에서의 Query Factory 사용 예시[](#애플리케이션-코드에서의-query-factory-사용-예시 "해당 헤딩으로 이동") ``` import { useParams } from "react-router-dom"; import { postApi } from "@/entities/post"; import { useQuery } from "@tanstack/react-query"; type Params = { postId: string; }; export const PostPage = () => { const { postId } = useParams
Loading...
;
}
if (isError || !post) {
return <>{error?.message};
}
return (
Post id: {post.id}
{post.title}
{post.body}
Owner: {post.userId}
`useQuery` 훅으로 `postQueries.list`를 호출하고, `Pagination` 컴포넌트와 연동하세요. @/pages/home/ui/index.tsx ``` export const HomePage = () => { const itemsOnScreen = DEFAULT_ITEMS_ON_SCREEN; const [page, setPage] = usePageParam(DEFAULT_PAGE); const { data, isFetching, isLoading } = useQuery( postApi.postQueries.list(page, itemsOnScreen), ); return ( <>
아래 코드를 `@/shared/api/query-client.ts`에 정의하세요. @/shared/api/query-client.ts ``` import { QueryClient } from "@tanstack/react-query"; export const queryClient = new QueryClient({ defaultOptions: { queries: { staleTime: 5 * 60 * 1000, gcTime: 5 * 60 * 1000, }, }, }); ``` ## 코드 자동 생성[](#코드-자동-생성 "해당 헤딩으로 이동") API 코드 자동 생성 도구를 사용하면 반복 작업을 줄일 수 있습니다.
다만, 직접 작성하는 방식보다 유연성이 떨어질 수 있습니다.
Swagger 파일이 잘 정의되어 있다면 자동 생성 도구를 활용해 코드를 생성하세요.
생성된 코드는 `@/shared/api` 디렉토리에 배치해 일관되게 관리합니다. ## React Query를 조직화하기 위한 추가 조언[](#react-query를-조직화하기-위한-추가-조언 "해당 헤딩으로 이동") ### API Client[](#api-client "해당 헤딩으로 이동") `shared/api`에 커스텀 APIClient 클래스를 정의하면 다음 기능을 한곳에서 일괄 설정할 수 있습니다: * response, request 로깅 및 에러 처리를 일관되게 적용 * 공통 헤더와 인증 설정, 데이터 직렬화 방식을 한곳에서 설정 * API endpoint 변경이나 옵션 업데이트를 단일 수정 지점에서 반영 @/shared/api/api-client.ts ``` import { API_URL } from "@/shared/config"; export class ApiClient { private baseUrl: string; constructor(url: string) { this.baseUrl = url; } async handleResponse
코드를 나눌 때는 각 부분이 **어떤 기능을 담당하는지**와 **다른 코드에 얼마나 의존하는지**를 기준으로 합니다.
Layer마다 **어떤 역할을 맡는지**에 대한 공통된 의미가 있습니다. 총 **7개의 Layer**가 있으며, **담당 기능과 의존성이 많은 것**부터 **적은 것** 순으로 나열합니다.   1. App 2. Processes (deprecated) 3. Pages 4. Widgets 5. Features 6. Entities 7. Shared > 모든 Layer를 꼭 써야 하는 건 아닙니다. **필요할 때만** 추가하세요.
대부분의 프론트엔드 프로젝트는 최소한 `shared`, `page`, `app`은 포함합니다. 실무에서는 폴더명을 소문자로 작성합니다(예: `📁 shared`, `📁 page`, `📁 app`).
**새로운 Layer를 만드는 것은 권장하지 않습니다**(역할이 이미 표준화되어 있음). ## Import 규칙[](#import-규칙 "해당 헤딩으로 이동") Layer는 **Slice(서로 밀접하게 연관된 모듈 묶음)** 로 구성됩니다.
Slice 간 연결은 **Layer Import 규칙**으로 제한합니다. > **규칙**: Slice 안의 코드는 **자신보다 아래 Layer**의 *다른 Slice*만 Import할 수 있습니다. 예: `📁 ~/features/aaa/api/request.ts`는 * 같은 Layer의 `📁 ~/features/bbb` → **불가능** * 더 아래 Layer(`📁 ~/entities`, `📁 ~/shared`) → **가능** * 같은 Slice(`📁 ~/features/aaa/lib/cache.ts`) → **가능** `app`과 `shared`는 **예외**입니다.
두 Layer는 **Layer이면서 동시에 하나의 큰 Slice처럼 동작**하고, 내부는 **Segment**로 나눕니다.
이 경우 Segment끼리 자유롭게 Import할 수 있습니다.
(`shared`는 비즈니스 도메인이 없고, `app`은 모든 도메인을 묶는 역할을 합니다.) ## Layer별 역할[](#layer별-역할 "해당 헤딩으로 이동") 각 Layer가 어떤 의미를 가지며, 어떤 코드를 포함하는지 정리했습니다. ### Shared[](#shared "해당 헤딩으로 이동") 앱의 **기본 구성 요소**를 모아둡니다.
백엔드, 서드파티 라이브러리, 실행 환경과의 연결, 그리고 **높은 응집도의 내부 라이브러리**를 포함합니다. * `app`과 마찬가지로 **Slice 없이 Segment로만 구성**합니다. * 비즈니스 도메인이 없으므로 **Shared 안의 파일끼리는 자유롭게 Import**할 수 있습니다. Segment 예시 * `📁 api` — API 클라이언트와 백엔드 요청 함수 * `📁 ui` — 공통 UI 컴포넌트 * **비즈니스 로직 제외**, **브랜드 테마 적용 가능** * 로고, 레이아웃, 자동완성/검색창 등 UI 로직 포함 가능 * 자동완성/검색창 등 **UI 로직 컴포넌트**도 가능 * `📁 lib` — 내부 라이브러리 * 단순 `utils/helpers` 모음이 아님 ([이 글 참고](https://dev.to/sergeysova/why-utils-helpers-is-a-dump-45fo)) * 하나의 주제(날짜, 색상, 텍스트 등)에 집중 * README로 역할과 범위를 문서화 * `📁 config` — 환경변수, 전역 Feature Flag * `📁 routes` — 라우트 상수/패턴 * `📁 i18n` — 번역 설정, 전역 문자열 > Segment 이름은 **무엇을 하는 폴더인지** 드러나야 합니다.
`components`, `hooks`, `types`처럼 역할이 불명확한 이름은 피하세요. ### Entities[](#entities "해당 헤딩으로 이동") 프로젝트에서 다루는 **핵심 데이터 개념**을 나타냅니다.
비즈니스 용어(예: `User`, `Post`, `Product`)와 일치하는 경우가 많습니다. Entity Slice에는 다음을 포함할 수 있습니다: 구성 * `📁 model` — 데이터 상태와 검증 스키마 * `📁 api` — 해당 Entity의 API 요청 * `📁 ui` — Entity의 시각적 표현 * 완전한 UI 블록이 아니어도 됨 * 여러 페이지에서 재사용 가능하게 설계 * 비즈니스 로직은 props/slot으로 연결 권장 #### Entity 간 관계[](#entity-간-관계 "해당 헤딩으로 이동") 원칙적으로 Slice끼리는 서로 모르면 좋습니다.
하지만 현실적으로 **다른 Entity를 포함**하거나 **상호작용**하는 경우가 있습니다.
이때는 로직을 **상위 Layer(Feature/Page)** 로 올려 처리하세요. 만약 한 Entity 데이터에 다른 Entity가 포함된다면,
`@x` 표기를 사용해 **교차 Public API**로 연결을 명시적으로 드러내세요. entities/artist/model/artist.ts ``` import type { Song } from "entities/song/@x/artist"; export interface Artist { name: string; songs: Array
여러 페이지에서 재사용되거나, 한 페이지에 큰 블록이 여럿 있을 때 유용합니다. tip * 재사용되지 않고 특정 페이지의 핵심 콘텐츠라면 Widget으로 분리하지 말고 Page 안에 두세요. * Nested Routing(예: [Remix](https://remix.run)) 환경에서는 Widget이 **Page와 유사한 방식**으로 동작합니다.
예를 들어, 데이터 로딩, 로딩 상태 표시, 에러 처리 등을 포함해 **하나의 라우터 단위 블록**을 구성할 수 있습니다. ### Page[](#page "해당 헤딩으로 이동") 웹/앱의 **화면(screen) 또는 액티비티(activity)** 에 해당합니다. 대부분 페이지 1개 = Slice 1개이지만, 유사한 페이지는 하나의 Slice로 묶을 수 있습니다. * 코드 찾기만 쉽다면 Page Slice 크기 제한은 없습니다. * 재사용되지 않는 UI는 Page 안에 둡니다. * 보통 전용 모델은 없고, 간단한 상태만 컴포넌트 내부에서 관리합니다. 구성 예 * 📁 ui — UI, 로딩 상태, 에러 처리 * 📁 api — 데이터 패칭/변경 요청 ### Process[](#process "해당 헤딩으로 이동") caution Deprecated — 기존 코드는 feature나 app으로 옮기세요. 과거에는 여러 페이지를 넘나드는 기능을 위한 탈출구 역할이었지만, 정의가 모호해 대부분의 앱에서는 사용하지 않습니다.
라우터, 서버 레벨 로직은 App Layer에 두고, App이 너무 커질 때만 제한적으로 고려하세요. ### App[](#app "해당 헤딩으로 이동") 앱 전역에서 동작하는 **환경 설정**과 **공용 로직**을 관리하는 Layer입니다.
예를 들어, 라우터 설정, 전역 상태 관리, 글로벌 스타일, 진입점 설정 등 **앱 전체에 영향을 주는 코드**를 둡니다. * shared처럼 Slice 없이 Segment로 구성합니다. * 대표 Segment: * `📁 routes` — Router 설정 * `📁 store` — Global State Store 설정 * `📁 styles` — Global Style * `📁 entrypoint` — Application Entry Point와 Framework 설정 --- # Public API Public API는 **Slice 기능을 외부에서 사용할 수 있는 공식 경로**입니다.
외부 코드는 반드시 이 경로를 통해서만 Slice 내부의 특정 객체에 접근할 수 있습니다.
즉, **Slice와 외부 코드 간의 계약(Contract)** 이자 **접근 게이트(Gate)** 역할을 합니다. 일반적으로 Public API는 **Re-export를 모아둔 index 파일**로 만듭니다. pages/auth/index.js ``` export { LoginPage } from "./ui/LoginPage"; export { RegisterPage } from "./ui/RegisterPage"; ``` ## 좋은 Public API의 조건[](#좋은-public-api의-조건 "해당 헤딩으로 이동") 좋은 Public API는 Slice를 **다른 코드와 통합하기 쉽고, 안정적으로 유지보수**할 수 있게 해줍니다.
이를 위해 다음 세 가지 목표를 충족하는 것이 이상적입니다. 1. **내부 구조 변경에 영향 없음** — Slice 내부 폴더 구조를 바꿔도 외부 코드는 그대로 동작해야 합니다. 2. **주요 동작 변경 = API 변경** — Slice의 동작이 크게 바뀌어 기존 기대를 깨면, Public API도 변경되어야 합니다. 3. **필요한 부분만 노출** — Slice 전체가 아니라 꼭 필요한 기능만 외부에 공개합니다. ### 안 좋은 예: 무분별한 Wildcard Re-export[](#안-좋은-예-무분별한-wildcard-re-export "해당 헤딩으로 이동") 개발 초기에는 편의상 모든 `export *`를 한 번에 노출하고 싶을 때가 있습니다.
이 경우 `export *` 같은 와일드카드 Re-export를 쓰기 쉽지만, 이는 Slice의 인터페이스를 불명확하게 만듭니다. Bad practice, features/comments/index.js ``` // ❌ 이렇게 하지 마세요 export * from "./ui/Comment"; // 👎 무분별한 UI export export * from "./model/comments"; // 💩 내부 모델 노출 ``` 문제가 되는 이유: * **발견 가능성 저하** — Public API에서 어떤 기능을 제공하는지 한눈에 알기 어렵습니다. * **내부 구현 노출** — 의도치 않게 Slice 내부 코드를 외부에서 사용하게 되고, 그 코드에 의존하면 리팩터링이 매우 어려워집니다. ## Cross-Import를 위한 Public API[](#public-api-for-cross-imports "해당 헤딩으로 이동") **Cross-import**는 같은 Layer 안에서 한 Slice가 다른 Slice를 import하는 것을 말합니다.
[Layer Import Rule](/documentation/kr/docs/reference/layers.md#import-rule-on-layers)에 따라 원칙적으로 금지되지만, **Entity 간 참조**처럼 불가피한 경우가 있습니다. 예를 들어, 비즈니스 도메인에서 `Artist`와 `Song`이 서로 연결되는 관계가 있다면, 우회하기보다 코드에 그대로 반영하는 것이 좋습니다. 이때는 `@x` 표기를 사용해 **전용 Public API**를 명시적으로 만듭니다. * `📂 entities` * `📂 A` * `📂 @x` * `📄 B.ts` — `entities/B/` 전용 Public API * `📄 index.ts` — 일반 Public API `entities/song`에서는 이렇게 import합니다. ``` import type { Artist } from "entities/artist/@x/song"; ``` `artist/@x/song`은 **Artist와 Song의 교차 지점** 을 의미합니다. note Cross-import는 최소화해야 하며, **Entity Layer**에서만 사용하세요.
다른 Layer에서는 의존 관계를 제거하는 것이 좋습니다. ## Index File 사용 시 주의사항[](#index-file-사용-시-주의사항 "해당 헤딩으로 이동") ### Circular Import (순환 참조)[](#circular-import-순환-참조 "해당 헤딩으로 이동") Circular Import는 두 개 이상의 파일이 서로를 참조하는 구조를 말합니다.
이 구조는 Bundler가 처리하기 어렵고, 디버그하기 힘든 런타임 오류를 유발할 수 있습니다. 순환 참조는 Index 파일 없이도 발생할 수 있지만, Index 파일은 특히 이런 실수를 만들기 쉽습니다.
예를 들어, Slice의 Public API에서 `HomePage`와 `loadUserStatistics`를 export하고, `HomePage`가 다시 Public API를 통해 `loadUserStatistics`를 가져오면 다음과 같이 순환이 생깁니다.  위 그림: `fileA.js`, `fileB.js`, `fileC.js` 파일의 Circular Import 예시 pages/home/ui/HomePage.jsx ``` import { loadUserStatistics } from "../"; // pages/home/index.js에서 import export function HomePage() { /* … */ } ``` pages/home/index.js ``` export { HomePage } from "./ui/HomePage"; export { loadUserStatistics } from "./api/loadUserStatistics"; ``` 위 구조에서는 `index.js`가 `HomePage`를 가져오고, `HomePage.jsx`는 다시 `index.js`를 통해 `loadUserStatistics`를 가져오면서 순환이 발생합니다. 여기서는 `index.js` → `HomePage.jsx`→ `index.js` 순환이 발생합니다. #### 예방 원칙[](#예방-원칙 "해당 헤딩으로 이동") * 같은 Slice 내부: 상대 경로(`../api/loadUserStatistics`)로 import하고, 경로를 명확히 작성 * 다른 Slice: 절대 경로(예: `@/features/...`)나 Alias를 사용 Index에서 export한 모듈이 다시 Index를 참조하지 않도록 주의 ### Large Bundle & Tree-shaking 문제[](#large-bundles "해당 헤딩으로 이동") 일부 Bundler는 Index 파일에서 모든 모듈을 export할 때 **미사용 코드**를 제대로 제거(Tree-shaking)하지 못할 수 있습니다. 대부분의 Public API에서는 모듈 간 연관성이 높아 문제가 되지 않지만, `shared/ui`와 `shared/lib`처럼 **서로 관련 없는 모듈 집합**에서는 문제가 심각해집니다. * `📂 shared/ui/` * `📁 button` * `📁 text-field` * `📁 carousel` * `📁 accordion` 여기서 `Button` 하나만 사용해도 `carousel`이나 `accordion` 같은 무거운 의존성이 번들에 포함될 수 있습니다.
특히 Syntax Highlighter, Drag-and-Drop 라이브러리처럼 용량이 큰 의존성은 영향을 크게 줍니다. #### 해결 방법[](#해결-방법 "해당 헤딩으로 이동") * 각 컴포넌트/라이브러리별로 별도 Index 파일 생성 * `📂 shared/ui/` * `📂 button` * `📄 index.js` * `📂 text-field` * `📄 index.js` * 직접 import pages/sign-in/ui/SignInPage.jsx ``` import { Button } from '@/shared/ui/button'; import { TextField } from '@/shared/ui/text-field'; ``` 이렇게 하면 필요한 코드만 번들에 포함되어 Tree-shaking이 잘 동작합니다. ### Public API 우회 방지의 한계[](#public-api-우회-방지의-한계 "해당 헤딩으로 이동") Slice에 Index 파일을 만들어도 직접 경로 import를 완전히 막을 수 없습니다.
특히 IDE의 Auto Import 기능이 잘못된 경로를 선택해 Public API 규칙을 어길 수 있습니다. #### 해결 방법[](#해결-방법-1 "해당 헤딩으로 이동") * [Steiger](https://github.com/feature-sliced/steiger)와 같은 FSD 전용 아키텍처 린터로 import 경로를 검사·강제 ### 대규모 프로젝트에서의 Bundler 성능 문제[](#대규모-프로젝트에서의-bundler-성능-문제 "해당 헤딩으로 이동") [TkDodo 글](https://tkdodo.eu/blog/please-stop-using-barrel-files)에서도 지적했듯,
Index 파일이 많아지면 개발 서버(HMR) 속도가 느려질 수 있습니다. #### 최적화 방법[](#최적화-방법 "해당 헤딩으로 이동") 1. [Large Bundle & Tree-shaking 문제](#large-bundles) 방식 적용 — `shared/ui`와 `shared/lib`에 대형 Index 대신 컴포넌트별 Index 사용 2. Segment 단위의 불필요한 Index 파일 생성 방지
예: `📄 features/comments/index.js`가 있다면, `📄 features/comments/ui/index.js` 같은 중첩 Index는 불필요 3. 큰 프로젝트는 기능 단위로 여러 Chunk(또는 패키지)로 나누기 * Google Docs처럼 Document Editor와 File Browser를 분리 * Monorepo에서 각 패키지를 독립 FSD Root로 구성 * 일부 패키지는 Shared·Entity Layer만 포함 * 다른 패키지는 Page·App Layer만 포함 * 필요한 경우 작은 Shared를 갖고 다른 패키지의 큰 Shared를 참조 --- # Slices and segments ## Slice[](#slice "해당 헤딩으로 이동") Slice는 Feature-Sliced Design 조직 구조의 **두 번째 계층**입니다.
주 목적은 제품, 비즈니스, 또는 단순히 애플리케이션 관점에서 **관련 있는 코드를 하나로 묶는 것**입니다. Slice의 이름은 표준화되어 있지 않고, 애플리케이션의 비즈니스 도메인에 따라 결정됩니다. 예를 들어: * 사진 갤러리: `photo`, `effects`, `gallery-page` * 소셜 네트워크: `post`, `comments`, `news-feed` `Shared`와 `App` Layer는 Slice를 포함하지 않습니다.
Shared는 비즈니스 로직이 전혀 없어 제품 관점에서 의미가 없고, App은 애플리케이션 전체를 다루기 때문에 별도로 나눌 필요가 없습니다. ### Zero 결합도와 높은 응집도[](#zero-coupling-high-cohesion "해당 헤딩으로 이동") Slice는 **다른 Slice와 독립적**이며, **자신의 핵심 목적과 관련된 대부분의 코드**를 포함해야 합니다.
아래 그림은 **응집도(cohesion)** 와 **결합도(coupling)** 개념을 시각적으로 설명합니다.  Image inspired by
단, 다른 Slice가 사용할 수 있도록 **명확한 Public API**를 반드시 제공해야 합니다.
이 규칙은 **Slice Public API Rule**로 강제됩니다. > *모든 Slice(또는 Slice가 없는 Layer의 Segment)는 Public API를 정의해야 합니다.*
*외부 모듈은 Slice/Segment의 내부 구조가 아니라 Public API를 통해서만 접근할 수 있습니다.* Public API의 목적과 작성 방법은 [Public API Reference](/documentation/kr/docs/reference/public-api.md)에서 자세히 설명합니다. ### Slice Group[](#slice-group "해당 헤딩으로 이동") 연관성이 높은 Slice는 폴더로 묶어서 관리할 수 있습니다.
단, 다른 Slice와 동일하게 **격리 규칙**을 적용해야 하며, 그룹 내부에서도 **코드 공유는 불가능**합니다.  ## Segment[](#segment "해당 헤딩으로 이동") Segment는 FSD 구조에서 **세 번째이자 마지막 계층**이며,
코드를 **기술적 성격**에 따라 그룹화합니다. 표준 Segment: * `ui` — UI 관련: Component, Date Formatter, Style 등 * `api` — Backend 통신: Request Function, Data Type, Mapper 등 * `model` — Data Model: Schema, Interface, Store, Business Logic * `lib` — Slice 내부 Library 코드 * `config` — Configuration과 Feature Flag 각 Layer에서 Segment를 어떻게 활용하는지는 [Layer 페이지](/documentation/kr/docs/reference/layers.md#layer-definitions)를 참고하세요. 또한 **커스텀 Segment**를 만들 수 있습니다.
특히 `App` Layer와 `Shared` Layer는 Slice가 없기 때문에, 커스텀 Segment가 자주 사용됩니다. Segment 이름은 **내용의 본질(components/hooks/types)** 이 아니라 **목적**을 설명해야 합니다.
예를 들어 `components`, `hooks`, `types` 같은 이름은 찾을 때 도움이 되지 않으므로 피하세요. --- ### 명시적 비즈니스 로직 도메인별로 코드를 구분해 필요한 로직을 즉시 찾을 수 있습니다. ---