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 관련 설정을 **한 곳에서** 관리합니다.
즉, 공통 설정을 client에 모아두면 개별 endpoint 로직에서는 **request를 보내는 데만** 집중할 수 있습니다. `client.ts`에서는 다음 항목들을 설정합니다: * 백엔드 기본 URL * Default headers (예: 인증 header) * JSON 직렬화/파싱 아래 예시에서 axios 버전과 fetch 버전 모두 확인할 수 있습니다. * 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` 폴더 안에 API endpoint별 request 함수를 작성합니다.
이렇게 endpoint 단위로 분리해두면 API 변경이 있을 때 유지보수가 매우 쉬워집니다. note 예제를 단순화하기 위해 form handling이나 입력 검증(Zod/Valibot)은 생략했습니다.
필요하다면 아래 문서를 참고하세요:
[Type Validation and Schemas](/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 함수와 타입들을 공개 API로 내보냅니다: 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); } ``` 이 함수는 **로그인 페이지 내부에서만 사용하는 API 요청** 이므로
slice의 public API(`index.ts`)로 다시 export할 필요는 없습니다. note entities layer에는 **backend response 타입**이나 **API 요청 함수**를 직접 두지 마세요.
그 이유는 backend 구조와 `entities` 구조가 서로 **역할과 책임이 다르기 때문입니다**. * `shared/api` 또는 각 slice의 `api` 폴더에서는 **백엔드에서 온 데이터**를 다루고, * `entities`에서는 **프론트엔드 관점에서 필요한 데이터 구조**에 집중해야 합니다.
(예: UI 표시용 데이터, 도메인 로직 처리용 데이터 등) ## 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-입력-수집 "해당 헤딩으로 이동") 이 단계에서는 사용자가 로그인에 필요한 정보를 입력할 수 있는 UI를 준비합니다. > OAuth 로그인만 사용한다면, **2단계(credential 전송)** 에서 별도로 아이디/비밀번호를 보내지 않습니다.
이 경우 바로 [token 저장](#how-to-store-the-token-for-authenticated-requests) 단계로 넘어갑니다. ### 1-1. 로그인 전용 페이지[](#1-1-로그인-전용-페이지 "해당 헤딩으로 이동") 웹 애플리케이션에서는 일반적으로 **/login** 같은 로그인 Form 전용 페이지를 만들어, 사용자가 **사용자 이름 / 이메일, 비밀번호**를 입력하도록 합니다. 이 페이지는 하는 일이 단순하기 때문에, 추가적인 **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 element와 form submit handler만 포함하도록 해서,
복잡한 비즈니스 로직은 다른 segment로 분리하고 UI는 단순하게 유지합니다. ### 1-2. 로그인 dialog 만들기[](#1-2-로그인-dialog-만들기 "해당 헤딩으로 이동") 어떤 페이지에서든 공통으로 사용할 수 있는 로그인 dialog가 필요하다면, 이를 **재사용 가능한 widget**으로 구현하는 것이 좋습니다.
**widget**으로 구현하면 페이지마다 로그인 로직을 따로 만들 필요 없이, 필요한 곳에서 동일한 dialog를 불러와 사용할 수 있고,
구조를 과하게 쪼개지 않으면서도 재사용성을 확보할 수 있습니다. ``` - 📂 widgets - 📂 login-dialog - 📂 ui - 📄 LoginDialog.tsx - 📄 index.ts - other widgets… ``` > 이후 설명은 **로그인 전용 페이지** 를 기준으로 진행하지만,
여기서 다루는 원칙은 login dialog widget에도 동일하게 적용됩니다. ### 1-3. Client-side Validation[](#1-3-client-side-validation "해당 헤딩으로 이동") 회원가입 페이지에서 잘못된 입력을 즉시 알려주면 UX가 훨씬 좋아집니다.
이를 위해 client-side validation을 적용할 수 있습니다. 검증 규칙은 `pages/login/model` segment에 schema 형태로 정의하고,`ui` segment에서는 이 schema를 불러와 재사용합니다.
아래 예시는 [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를 사용해 form으로부터 받은 데이터를 검증할 수 있습니다: 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 * 기타 state 관리/요청 로직 즉, **어디에서나 재사용 가능한 로그인 요청 함수** 를 만든다고 보면 됩니다. ### 2-1. 함수 placement[](#2-1-함수-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` 등)를 감싼 공용 API client로,
**기본 URL, 공통 헤더, request/response 직렬화** 등을 처리합니다. 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에-저장하기 "해당 헤딩으로 이동") 로그인 request가 로그인 페이지에서만 사용된다면,
해당 페이지의 api segment에 login 함수를 두는 것도 가능합니다. ``` - 📂 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)[](#two-factor-auth-2fa "해당 헤딩으로 이동") 2단계 인증(2FA)을 사용하는 경우에는 로그인 플로우에 한 단계가 더 추가됩니다. 1. `/login` 응답에 `has2FA` 플래그가 있으면, `/login/2fa` 페이지로 redirect 합니다. 2. 2FA 페이지와 관련 API들은 모두 `pages/login` slice에 함께 둡니다. 3. `/2fa/verify`와 같이 별도의 endpoint를 호출하는 함수는 `shared/api` 또는 `pages/login/api`에 배치합니다. 이렇게 하면, 일반 로그인과 2FA 관련 로직을 **login slice 내부**에 모아둘 수 있습니다. ## Authenticated Requests를 위한 token 저장[](#how-to-store-the-token-for-authenticated-requests "해당 헤딩으로 이동") 로그인, 비밀번호 변경, OAuth, 2단계 인증 등 어떤 방법으로 인증을 하든,
인증 API 호출의 **응답(response)** 으로 보통 token이 함께 내려옵니다. 이 token을 어딘가에 저장해 두면,
이후 **모든 인증이 필요한 API 요청(request)** 에 token을 자동으로 포함시켜 백엔드 인증을 통과할 수 있습니다. 웹 애플리케이션에서 token을 저장하는 방법 중 **가장 권장되는 방식은 cookie**입니다. cookie를 사용하면, 브라우저가 요청마다 token을 자동으로 넣어 주기 때문에
프론트엔드에서 token을 직접 관리할 필요가 거의 없습니다.
따라서 프론트엔드 아키텍처 차원에서 신경 쓸 부분이 크게 줄어듭니다. 사용 중인 프레임워크가 서버 사이드 기능을 제공한다면(예: [Remix](https://remix.run)),
서버 측 cookie 관련 로직을 shared/api에 두는 것을 권장합니다. Remix에서의 구현 예시는 [튜토리얼의 Authentication 섹션](/kr/docs/get-started/tutorial.md#authentication)을 참고하면 됩니다. 하지만 cookie를 사용할 수 없는 환경도 있습니다.
이 경우에는 token을 클라이언트에서 직접 저장하고, token 만료를 감지하고,
refresh token을 사용해 새 token을 발급받고 기존 요청을 다시 실행하는 등의 로직을 함께 구현해야 합니다. FSD에서는 여기서 한 가지 추가 고민이 필요합니다. token을 **어느 layer 또는 어느 segment에** 저장할지,
그렇게 저장한 token을 앱 전역에서 **어떻게** 사용할 수 있게 할지에 따라 전체 구조가 달라지기 때문입니다. ### 3-1. Shared[](#3-1-shared "해당 헤딩으로 이동") Shared layer에 token을 두는 방식은 shared/api에 정의된 **공용 API 클라이언트**와 자연스럽게 결합되는 패턴입니다. token을 module scope나 어떤 reactive store에 저장해 두면,
인증이 필요한 다른 API 함수에서 이 token을 **그대로 참조**해 사용할 수 있습니다. token 자동 재발급(refresh)은 API client의 **middleware**에서 담당합니다. 1. 로그인 시 **access token, refresh token**을 저장합니다. 2. 인증이 필요한 request를 보냅니다. 3. 응답에서 token 만료 코드를 받으면, refresh token으로 새 token을 발급해 저장한 뒤 실패한 request을 동일하게 다시 시도합니다. #### Token 관리 분리 전략[](#token-관리-분리-전략 "해당 헤딩으로 이동") * **전담 segment 부재**
token 저장과 재발급 로직이 request 로직과 같은 파일에 뒤섞여 있으면, 코드가 많아질수록 유지보수가 점점 어려워집니다.
이런 경우에는 **request 함수와 client는 `shared/api`에 두고**,
**token 관리 로직은 `shared/auth` segment로 분리**하는 방식을 권장합니다. * **token과 사용자 정보를 함께 받는 경우**
백엔드가 token과 동시에 **현재 사용자 정보**를 반환하는 API를 제공하는 경우도 있습니다.
이때는 다음 두 가지 방식 중 하나로 처리할 수 있습니다. 1. 별도 store에 함께 저장하거나 2. `/me`·`/users/current` 같은 endpoint를 따로 호출해 user 정보를 가져올 수 있습니다. ### 3-2. Entities[](#3-2-entities "해당 헤딩으로 이동") FSD 프로젝트에서는 보통 **User entity**(또는 **Current User entity**)를 두는 경우가 많습니다.
두 entity를 하나로 합쳐서 사용하는 것도 전혀 문제 없습니다. note **Current User**는 `viewer` 또는 `me`라고 부르기도 합니다.
이는 권한과 개인 정보가 있는 **현재 로그인한 단일 사용자**와,
공개적으로 표시되는 **여러 사용자 목록**을 구분하기 위해 쓰는 이름입니다. #### Token을 User Entities에 저장하기[](#token을-user-entities에-저장하기 "해당 헤딩으로 이동") User entity의 model segment에 **reactive store**를 만들고,
이곳에 token과 user 객체를 함께 보관할 수 있습니다. 이렇게 하면: **현재 로그인한 사용자 정보** 와 **그 사용자가 가진 token**을 한 곳에서 관리할 수 있어서,
인증과 관련된 비즈니스 로직을 작성할 때 구조를 이해하기 쉬워집니다. 다만 API client는 보통 shared/api에 정의되거나,
여러 entity에 분산되어 있는 경우가 많습니다. 따라서 layer의 import 규칙([import rule on layers](/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 — 권장하지 않음[](#3-3-pages--widgets--권장하지-않음 "해당 헤딩으로 이동") 다음과 같은 이유로 page layer나 widget layer에 token을 저장하는 것은 권장하지 않습니다. page, widget layer에 token을 두면 전역에서 이 token에 의존하게 되는데,
이렇게 되면 다른 slice에서 재사용하기 어렵고, 구조가 쉽게 얽힙니다. 따라서 token 저장 위치는 Shared 또는 Entities 중 하나로 결정하는 것을 권장합니다. ## 4. Logout & Token Invalidation[](#4-logout--token-invalidation "해당 헤딩으로 이동") ### 로그아웃과 token 무효화[](#로그아웃과-token-무효화 "해당 헤딩으로 이동") 대부분의 애플리케이션에는 **로그아웃 전용 페이지**는 따로 두지 않습니다.
대신, 어느 화면에서든 호출할 수 있는 로그아웃 기능을 두는 것이 일반적입니다. 로그아웃은 일반적으로 다음 두 단계로 이루어집니다. 1. 백엔드에 인증된 로그아웃 request 보내기 (예: `POST /logout`) 2. token store reset (access token / refresh token 모두 제거) > 모든 API request을 shared/api에 모아 관리하고 있다면,
로그아웃 API는 login() 근처, 예를 들어 shared/api/endpoints/logout.ts에 두는 것이 자연스럽습니다. > > 반대로 특정 UI(예: Header)에만 로그아웃 버튼이 있고,
그곳에서만 이 API를 호출한다면 widgets/header/api/logout.ts처럼
버튼이 위치한 widget 근처에 두는 것도 가능합니다. token store reset은 실제로 로그아웃 버튼을 가진 UI에서 트리거됩니다.
로그아웃 request와 store reset을 같은 widget의 model segment에 함께 두어도 됩니다. ### 자동 로그아웃[](#자동-로그아웃 "해당 헤딩으로 이동") 다음과 같은 경우에는 반드시 token store를 초기화해야 합니다. * 로그아웃 request가 실패했을 때 * 로그인 token 갱신(`/refresh`)이 실패했을 때 이 상황에서 token이 그대로 남아 있으면,
화면 상으로는 **로그인된 것처럼** 보이지만 실제로는 대부분의 요청이 실패하는 애매한 상태가 될 수 있습니다. > token을 Entities(User)에 보관했다면,
해당 entity의 model segment에 token 초기화 코드를 두는 것이 좋습니다.
Shared layer에서 token을 관리한다면, 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** 예시를 살펴보겠습니다.
이 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 내용은 **외부에서 주입(의존성 주입)** 받을 수 있도록 합니다. 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 (
중요한 포인트는 layout이 **틀만 제공하고, 구체적인 내용은 props로 받아서 렌더링한다** 는 점입니다. ## layout에 widget 적용하기[](#layout에-widget-적용하기 "해당 헤딩으로 이동") layout 컴포넌트에서 인증 처리나 데이터 로딩 같은 **비즈니스 로직**을 수행해야 할 때가 있습니다.
예를 들어, [React Router](https://reactrouter.com/)의 deeply nested routes 구조에서는 `/users`, `/users/:id`, `/users/:id/settings` 처럼
공통된 URL prefix를 가진 여러 child routes가 존재합니다. 이 경우, 인증 확인이나 공통 데이터 로딩 같은 로직을
각 페이지마다 작성하기보다는 **layout 레벨에서 한 번에 처리**하는 방식이 훨씬 효율적입니다. 다만 이런 layout을 shared나 widgets 폴더에 두면 [layer에 대한 import 규칙](/kr/docs/reference/layers.md#import-rule-on-layers)을 위반할 수 있습니다. > Slice의 module은 자신보다 **하위 layer**에 있는 Slice만 import할 수 있습니다. 즉, layout에서 entity/feature/page를 직접 불러오게 되면
**위에서 아래를 가져오는** 잘못된 의존성이 생길 수 있습니다. 그래서 먼저 아래와 같은 점을 고려하는 것이 좋습니다. * *이 layout이 정말 필요한가?* * *꼭 widget 형태로 만들 필요가 있는가?* layout이 적용되는 페이지 수가 2\~3곳 정도라면,
이 layout이 사실상 **특정 페이지만을 위한 wrapper**일 수도 있으며 굳이 widget으로 승격시킬 필요가 없을 수 있습니다. 이런 상황에서는 아래 두 가지 대안을 먼저 고려하세요. 1. **App layer에서 inline으로 작성하기**
URL 패턴이 공통된 여러 경로를 Router의 nesting 기능으로 묶어 하나의 route group으로 만들 수 있습니다.
이 route group에 layout을 한 번만 지정하면, 해당 그룹 아래 모든 페이지에 자동으로 동일한 layout이 적용됩니다. 2. **코드 복사 & 붙여넣기**
layout은 자주 변경되는 코드가 아니므로, 필요한 페이지만 layout 코드를 복사해 사용해도 큰 문제가 없습니다.
수정이 필요할 때만 해당 layout들을 개별적으로 업데이트하면 되고, 페이지 간 관계를 주석으로 남겨 두면 누락을 방지할 수 있습니다. *** 위 방법들이 프로젝트에 맞지 않다면, layout 안에서 widget을 사용하는 다음 두 가지 해결책을 고려할 수 있습니다. ### 1. Render Props 또는 Slots 사용하기[](#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 틀을 제공하고**,
자식 컴포넌트가 전달한 UI를 layout 내부 특정 위치에 **주입(injection)** 하는 구조입니다.
Layout이 비즈니스 로직을 직접 수행하면서도, UI 구성은 외부에서 유연하게 가져올 수 있다는 장점이 있습니다. ### 2. layout을 App layer로 이동하기[](#2-layout을-app-layer로-이동하기 "해당 헤딩으로 이동") layout을 app/layouts 같은 상위 layer로 옮기면,
App layer는 아래 layer(entities, features, shared)를 자유롭게 import할 수 있기 때문에
Layer 규칙을 위반하지 않고 layout 안에서 widget을 사용할 수 있습니다. ## 참고 자료[](#참고-자료 "해당 헤딩으로 이동") React 및 Remix(React Router와 구조가 유사)의
인증 layout 구현 예시는 [튜토리얼](/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 "해당 헤딩으로 이동") >
그리고 FSD 구조 안에서 **각 타입을 어디에 배치하는 것이 좋은지**를 설명합니다. info 더 궁금한 점이 있나요?
페이지 우측의 피드백 버튼을 눌러 의견을 남겨 주세요.
여러분의 제안은 이 문서를 개선하는 데 큰 도움이 됩니다! ## 유틸리티 타입[](#유틸리티-타입 "해당 헤딩으로 이동") 유틸리티 타입은 **그 자체로 큰 의미를 가지기보다는, 다른 타입과 함께 자주 사용되는 보조 타입**을 말합니다.
예를 들어, 배열에서 요소 타입만 추출하는 `ArrayValues` 같은 타입을 아래와 같이 정의할 수 있습니다. ``` type ArrayValues
대표적으로 [`type-fest`](https://github.com/sindresorhus/type-fest)를 설치해서 사용합니다. 2. **내부 유틸리티 타입 라이브러리 구축**
`shared/lib/utility-types` 폴더를 만들고, README에 다음 내용을 명확히 적어 두세요. * 우리 팀에서 **유틸리티 타입**이라고 부르는 기준 * 어떤 타입을 추가/제외할지에 대한 규칙 > 유틸리티 타입의 **재사용 가능성**을 과대평가하지 마세요.
**재사용 가능하다**는 이유만으로 꼭 전역(`shared`)에 둘 필요는 없습니다. 유틸리티 타입은 아래처럼 **실제 사용되는 위치 근처**에 두는 것이 오히려 유지보수에 유리한 경우가 많습니다. ``` - 📂 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 함수를 `entities/song/api` 내부에 두면 다음과 같은 문제가 생깁니다. `entities/artist` slice에서 `Song` 타입을 **참조하고 싶어도**,
FSD의 [layer별 import 규칙](/kr/docs/reference/layers.md#import-rule-on-layers) 때문에 **동일 layer 간(import)** 의존은 금지됩니다. * 규칙 요약: > *“한 slice의 모듈은 자신보다 **아래 layer**에 있는 slice만 import할 수 있다.”* 즉, 같은 layer에 있는 entity끼리는 직접 cross-import 할 수 없기 때문에 **Artist → Song** 의존을 바로 연결하기가 어렵습니다.
이런 경우에는 제네릭 타입 매개변수를 사용하거나, `@x` Public API 같은 패턴을 사용해 우회하는 전략이 필요합니다. ### 2. 상호 참조 해결 전략[](#2-상호-참조-해결-전략 "해당 헤딩으로 이동") entity끼리 서로를 참조해야 할 때 사용할 수 있는 대표적인 전략은 다음 두 가지입니다. #### 1. 제네릭 타입 매개변수화[](#1-제네릭-타입-매개변수화 "해당 헤딩으로 이동") entity 간에 연결이 필요한 타입에 제네릭 타입 매개변수를 선언하고, 필요한 제약 조건을 부여합니다.
예를 들어, Song 타입에 `ArtistType`이라는 제네릭을 두고 제약을 걸 수 있습니다. entities/song/model/song.ts ``` interface Song
반면, `Country-City`처럼 서로 강하게 결합된 구조는 깔끔하게 분리하기 어려울 수 있습니다. #### 2. Cross-import (Public API(@x) 활용)[](#2-cross-import-public-apix-활용 "해당 헤딩으로 이동") 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`와 매우 비슷하지만,
**artist에서 사용할 수 있는 부분**만 노출하는 역할을 합니다. entities/song/@x/artist.ts ``` export type { Song } from "../model/song.ts"; ``` 이렇게 분리해 두면 `📄 entities/artist/model/artist.ts`에서 `Song`을 가져올 때,
다음과 같이 **의존 대상이 명확한 import**를 사용할 수 있습니다. 이 방식은 entity들의 의존 관계를 코드 구조 상에서 명확하게 보여 주고, 도메인 간 분리를 유지하는 데 도움이 됩니다. entities/artist/model/artist.ts ``` import type { Song } from "entities/song/@x/artist"; export interface Artist { name: string; songs: Array
이럴 때 `mapper`를 사용해 DTO를 **프론트엔드 친화적인 형태**로 변환합니다. ### DTO 배치 위치[](#dto-배치-위치 "해당 헤딩으로 이동") DTO를 어디에 둘지는 백엔드와의 코드 공유 방식에 따라 달라집니다. * 백엔드 타입을 별도 패키지로 공유하고 있다면 → 해당 패키지에서 DTO를 가져와서 사용하면 됩니다. * 코드 공유가 없다면 → 프론트엔드 코드베이스 안 어딘가에 DTO를 정의해야 합니다. Request 함수가 `shared/api`에 있다면, DTO도 가능한 한 **바로 옆**에 두는 것을 권장합니다. shared/api/songs.ts ``` import type { ArtistDTO } from "./artists"; interface SongDTO { id: number; title: string; artist_ids: Array
Request와 store가 `entity slice` 내부에 있다면 → mapper도 해당 slice 안에 두되,
layer 간 cross-import 제한을 반드시 고려해야 합니다. entities/song/api/dto.ts ``` import type { ArtistDTO } from "entities/artist/@x/song"; export interface SongDTO { id: number; title: string; disc_no: number; artist_ids: Array
예를 들어 곡 정보에 저자(Author) 객체 전체가 포함되는 식입니다. 이럴 때 entity들끼리는 **서로의 존재를 완전히 모른 채** DTO 안에서만 연결될 수도 있습니다. 이 경우 간접 연결(middleware 등)로 우회하는 것보다,
`@x` 표기법을 활용해 **명시적으로 cross-import**를 허용하는 편이 나을 때가 많습니다.
(예: Redux Toolkit + Normalizr를 조합해 사용하는 패턴) entities/song/model/songs.ts ``` import { createSlice, createEntityAdapter, createAsyncThunk, createSelector, } from "@reduxjs/toolkit"; import { normalize, schema } from "normalizr"; import { getSong } from "../api/getSong"; // Normalizr entity schema export const artistEntity = new schema.Entity("artists"); export const songEntity = new schema.Entity("songs", { artists: [artistEntity], }); const songAdapter = createEntityAdapter(); export const fetchSong = createAsyncThunk( "songs/fetchSong", async (id: string) => { const data = await getSong(id); // 데이터를 정규화하여 리듀서가 예측 가능한 payload를 로드할 수 있도록 합니다: const normalized = normalize(data, songEntity); // `action.payload = { songs: {}, artists: {} }` return normalized.entities; }, ); export const slice = createSlice({ name: "songs", initialState: songAdapter.getInitialState(), reducers: {}, extraReducers: (builder) => { builder.addCase(fetchSong.fulfilled, (state, action) => { songAdapter.upsertMany(state, action.payload.songs); }); }, }); const reducer = slice.reducer; export default reducer; ``` entities/song/@x/artist.ts ``` export { fetchSong } from "../model/songs"; ``` entities/artist/model/artists.ts ``` import { createSlice, createEntityAdapter } from "@reduxjs/toolkit"; import { fetchSong } from "entities/song/@x/artist"; const artistAdapter = createEntityAdapter(); export const slice = createSlice({ name: "users", initialState: artistAdapter.getInitialState(), reducers: {}, extraReducers: (builder) => { builder.addCase(fetchSong.fulfilled, (state, action) => { // 같은 fetch 결과를 처리하며, 여기서 artists를 삽입합니다. artistAdapter.upsertMany(state, action.payload.artists); }); }, }); const reducer = slice.reducer; export default reducer; ``` 이 방법을 사용하면 slice 간 **완전한 독립성**은 다소 줄어들지만,
어차피 강하게 묶여 있는 두 entity의 관계를 코드 상에서 명확하게 드러낼 수 있다는 장점이 있습니다. 즉, 나중에 둘 중 하나를 수정할 때 **연결된 entity까지 함께 리팩토링해야 한다는 사실**을 더 쉽게 인지할 수 있습니다. ## Global 타입과 Redux[](#global-타입과-redux "해당 헤딩으로 이동") Global 타입은 애플리케이션 전역에서 사용되는 타입을 말하며, 크게 두 가지 종류로 나눌 수 있습니다. 1. 애플리케이션에 특화되지 않은 **제너릭 타입** 2. 애플리케이션 전체가 알고 있어야 하는 **전역 도메인 타입** ### 1) 제너릭 타입[](#1-제너릭-타입 "해당 헤딩으로 이동") 첫 번째 경우(특정 도메인에 묶이지 않은 제너릭 타입)는 `Shared` 폴더 안의 적절한 segment에 배치하면 됩니다.
예를 들어, **분석(analytics) 관련 전역 인터페이스**라면 `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
[import 규칙](/kr/docs/reference/layers.md#import-rule-on-layers)에 의해 App layer에 있는 `RootState`, `AppDispatch` 타입을 바로 가져올 수 없습니다. > 한 slice의 module은 자신보다 하위 layer에 있는 slice만 import할 수 있습니다. #### 권장 해결책[](#권장-해결책 "해당 헤딩으로 이동") 이 경우에는 **Shared ↔ App layer 간에 한정된 암묵적 의존성을 허용**하는 것이 현실적인 해결책입니다.
`RootState`, `AppDispatch` 타입은 자주 바뀌지 않고, Redux 사용 경험이 있는 개발자에게는 매우 익숙한 개념이기 때문에,
이 정도의 의존성은 유지보수 부담이 크지 않습니다. app/store/index.ts ``` /* 이전 코드 블록과 동일한 내용입니다… */ declare type RootState = ReturnType
역할에 따라 `api`, `ui` 등 적절한 segment를 선택합니다. ## 타입 검증 Schema와 Zod[](#타입-검증-schema와-zod "해당 헤딩으로 이동") 데이터의 형태와 제약 조건을 검증하려면 [Zod](https://zod.dev) 같은 라이브러리로 **validation schema**를 정의합니다. schema의 위치는 **어디에서 쓰이는 데이터인지**에 따라 결정합니다. * 백엔드 Response 검증 → `api` segment 근처 * 폼 입력 값 검증 → `ui` segment (또는 복잡한 경우 `model` segment) 검증 schema는 DTO를 받아 파싱하고, schema와 맞지 않으면 즉시 에러를 던집니다.
([Data transfer objects and mappers](#data-transfer-objects-and-mappers) 섹션도 참고하세요.) 특히 백엔드 Response가 예상한 schema와 일치하지 않을 때 request를 실패시키도록 구현하면,
버그를 비교적 이른 시점에 발견할 수 있습니다. 이 때문에 검증 schema는 보통 `api` segment에 두는 편이 일반적입니다. ## Component props, context 타입[](#component-props-context-타입 "해당 헤딩으로 이동") 일반적으로 Component의 props 타입과 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.md`에 다음 내용을 함께 기록해 두는 것을 추천합니다. * 이 폴더에 있는 파일들의 용도 * 타입을 재생성하는 방법 (스크립트 명령어 등) --- # 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 ```
아래 폴더 구조를 예시로 살펴보세요. (파란 화살표를 클릭하면 펼쳐집니다). 📁 src * 📁 actions * 📁 product * 📁 order * 📁 api * 📁 components * 📁 containers * 📁 constants * 📁 i18n * 📁 modules * 📁 helpers * 📁 routes * 📁 products.jsx * 📄 products.\[id].jsx * 📁 utils * 📁 reducers * 📁 selectors * 📁 styles * 📄 App.jsx * 📄 index.js ## 시작 전 체크리스트[](#before-you-start "해당 헤딩으로 이동") Feature-Sliced Design(FSD)이 **정말 필요한지 먼저 확인하세요.**
모든 프로젝트가 새로운 아키텍처를 요구하는 것은 아닙니다. ### 전환을 고려해야 할 징후[](#전환을-고려해야-할-징후 "해당 헤딩으로 이동") 1. 신규 팀원이 프로젝트에 적응하기 어려워하는 경우 2. 코드 일부를 수정할 때, 관련 없는 다른 코드에 오류가 발생하는 경우가 **잦은** 경우 3. 새 기능을 추가할 때 고려해야 할 사항이 너무 많아 어려움을 겪는 경우 **팀의 합의 없이 FSD 전환을 시작하지 마세요.**
팀 리더라도 전환의 이점이 학습/전환 비용을 상회한다는 점을 먼저 설득해야 합니다.
또한, 개선 효과가 바로 눈에 띄지 않을 수 있으므로 **팀원** 및 **프로젝트 매니저(PM)** 의 승인을 사전에 확보하고 이점을 공유하세요. PM 설득 시 고려할 사항 * FSD 전환은 단계적으로 진행할 수 있어 기존 기능 개발을 중단하지 않아도 됩니다. * 명확한 아키텍처 구조는 신규 개발자 온보딩 시간을 단축합니다. * 공식 문서를 활용하면 별도 문서 유지·관리 비용을 절감할 수 있습니다. *** 마이그레이션을 시작하기로 결정했다면, `📁 src` 폴더에 별칭(alias)을 설정하는 것을 첫 단계로 삼으세요.
## 1단계: 페이지 단위로 코드 분리하기[](#divide-code-by-pages "해당 헤딩으로 이동") 대부분의 커스텀 아키텍처는 규모와 관계없이 이미 어느 정도 페이지 단위로 코드를 나누고 있습니다.
`📁 pages` 폴더가 있다면 이 단계를 건너뛰어도 됩니다. 위에 예시 폴더처럼 `📁 routes`만 있다면 다음 순서를 따르세요. 1. `📁 pages` 폴더를 새로 만듭니다. 2. `📁 routes`에 있던 **페이지용 컴포넌트**를 가능한 한 모두 `📁 pages` 폴더로 옮깁니다. 3. 코드를 옮길 때마다 해당 페이지 전용 폴더를 만들고 그 안에 `index.tsx` 파일을 추가해 **진입점(entry point)** 를 노출합니다. note 이 단계에서는 **Page A에서 Page B의 코드를 import**해도 괜찮습니다.
나중 단계에서 이러한 의존성을 분리할 예정이니, 우선 **페이지 폴더를 만드는 것**에 집중하세요. **📁 Route File** 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 "해당 헤딩으로 이동") **📁 src/shared 폴더를 만들고,** 📁 pages 또는 📁 routes를 import하지 않는 모든(파일)은 이 폴더로 모읍니다.
**📁 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 "해당 헤딩으로 이동") 한 페이지가 다른 페이지의 코드를 직접 import하고 있다면, 아래 두 가지 방식 중 하나로 의존성을 정리합니다. | 방법 | 사용 시점 | | ----------------------------------- | -------------------------------------------------------------- | | **A. 코드 복사하여 독립시키기** | 페이지별로 로직이 달라질 가능성이 높거나, 재사용성이 낮은 경우 | | **B. Shared로 이동하여 공통화하기** | 여러 페이지에서 반복적으로 사용되는 경우 | * Shared 이동 위치 예시 * UI 구성 요소 → `📁 shared/ui` * 설정 상수 → `📁 shared/config` * 백엔드 호출 → `📁 shared/api` note 코드를 복사하는 것은 잘못이 아닙니다.
경우에 따라서는 **중복을 허용하더라도 페이지 간 의존성을 줄이는 것**이 더 중요합니다.
다만, 비즈니스 로직처럼 변경 가능성이 큰 핵심 부분은 중복을 피하고, 복사할 때에도 가능한 한 DRY 원칙을 고려합니다. ## 4단계: Shared Layer 정리하기[](#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. **각 페이지 내부**에서, 필요한 `segment(ui, model, api 등)`를 구성합니다. 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**를 표현합니다.
이러한 slice는 **Entities layer**로 이동하며, **entity**마다 별도의 폴더를 구성합니다.
반대로, 댓글 작성처럼 **사용자의 특정 행동(action)** 을 중심으로 한 **slice**는 **Features layer**로 옮겨 독립적으로 관리합니다. **Entities**와 **Features**는 서로 의존하지 않고 사용할 수 있도록 설계해야 합니다.
Entity 간의 관계가 필요하다면 [Business-Entities Cross-Relations 가이드](/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)** 입니다.
v2는 기존 장점을 유지하는 동시에 이러한 문제들을 보완하도록 설계되었습니다.
또한 [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** 라는 세 가지 개념만 이해하면 구조적 결정을 쉽게 내릴 수 있습니다.
덕분에 신규 팀원이 **어디에 어디에 둘지** 고민할 필요가 줄어들어 온보딩 속도가 크게 향상됩니다. ### 유연한 모듈화[](#유연한-모듈화 "해당 헤딩으로 이동") * **독립 영역**은 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 의존 규칙](https://t.me/atomicdesign/18708)을 명확히 설정할 수 있도록 돕습니다.
**상위 layer**는 더 넓은 **context**를 제공하며, **하위 layer**는 더 낮은 **변경 리스크와 높은 재사용성**을 갖습니다. ### 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 권장 네이밍과 이전 명칭 간의 대응 관계입니다.
아래에서는 v2 권장 layer·segment 명칭을 이전 명칭과 대응하여 정리했습니다.
추상화/네이밍 관련 상세 가이드는 [명확한 네이밍 권장사항](/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 원칙](/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이기 때문입니다. v2.1의 핵심 원칙은 다음과 같습니다: * Page 내부에 주요 UI와 비즈니스 로직을 배치합니다. * Shared layer에는 순수 재사용 요소만 유지합니다. * 여러 Page에서 실제로 공유되는 로직만 Feature/Entity로 분리합니다. 이 접근 방식의 장점 1. **Page가 명확한 책임 단위**가 되어, 코드의 역할이 분명해집니다. 2. **Shared** layer가 불필요하게 비대해지는 것을 방지해 의존성이 간결해집니다. 3. 공통 로직을 실제로 재사용할 때만 분리하므로 과도한 추상화가 줄어듭니다. 또한 v2.1에서는 **Entity 간 cross-import**를 위한 `@x` 표기법이 **표준화**되었습니다.
이를 통해 import 경로를 더 명확하고 일관되게 관리할 수 있습니다. ## 마이그레이션 프로세스[](#how-to-migrate "해당 헤딩으로 이동") v2.1은 하위 호환성을 제공합니다.
즉, 기존 v2.0 프로젝트는 **수정 없이** 그대로 동작합니다.
다만 v2.1의 구조적 장점을 활용하려면 아래 단계를 차례로 적용하면 됩니다. ### 1. Slice 병합[](#1-slice-병합 "해당 헤딩으로 이동") v2.1 Page-First 모델에서는 **여러 Page에서 재사용되지 않는** slice는 Page 내부로 병합하는 것을 권장합니다.
이렇게 하면 코드 탐색이 빨라지고 유지보수 비용도 줄어듭니다. #### Steiger로 자동 탐지하기[](#steiger로-자동-탐지하기 "해당 헤딩으로 이동") 프로젝트 루트에서 [Steiger](https://github.com/feature-sliced/steiger)를 실행하면 v2.1 mental model에 맞추어 slice 사용 여부를 자동으로 분석해줍니다: ``` npx steiger src ``` * [`insignificant-slice`](https://github.com/feature-sliced/steiger/tree/master/packages/steiger-plugin-fsd/src/insignificant-slice)
단일 Page에서만 사용되는 slice를 탐지합니다. → **Page 내부로 병합하는 것을 권장**합니다. * [`excessive-slicing`](https://github.com/feature-sliced/steiger/tree/master/packages/steiger-plugin-fsd/src/excessive-slicing)
지나치게 잘게 나뉜 slice를 찾아줍니다. → **유사한 slice를 통합하거나 그룹화하여 탐색성**을 높입니다. 이 명령으로 `한 번만 쓰이는 slice` 목록이 출력됩니다.
이제 각 slice의 재사용 여부를 검토하고, 과하다면 해당 page로 병합하거나 비슷한 역할끼리 묶어 보세요. Slice 관리 Slice는 해당 layer의 namespace를 구성하는 요소입니다.
전역 변수를 최소화하듯, slice도 실제로 재사용되는 경우에만 독립 단위로 유지하세요. 한 곳에서만 쓰이는 slice → Page 또는 Feature 내부로 이동
여러 Page에서 재사용되는 slice → 그대로 유지 ### 2. Cross Import 표준화[](#2-cross-import-표준화 "해당 헤딩으로 이동") v2.1에서는 Entity 간 cross-import를 위해 `@x-` 표기법을 사용합니다. entities/B/some/file.ts ``` // v2.1 권장 방식 import type { EntityA } from "entities/A/@x/B"; ``` 자세한 내용은 [Public API for cross-imports](/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나 내부 문서에 반드시 기록해야 합니다.
이 내용을 [프로젝트 지식](/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](/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는 **이 Layer에는 어떤 코드가 와야 하는지**에 대해 **공통된 의미와 책임**이 정해져 있습니다. 총 **7개의 Layer**가 있으며, 아래로 내려갈수록 **담당하는 기능과 의존성이 줄어드는 순서**입니다.   1. App 2. Processes (deprecated) 3. Pages 4. Widgets 5. Features 6. Entities 7. Shared > 모든 Layer를 반드시 사용해야 하는 것은 아닙니다.
**필요한 경우에만** Layer를 추가하세요.
대부분의 프론트엔드 프로젝트는 보통 최소한 `shared`, `page`, `app` 정도는 사용합니다. 실무에서는 폴더명을 보통 소문자로 작성합니다. (예: `📁 shared`, `📁 page`, `📁 app`)
또한, **새로운 Layer를 직접 정의해서 사용하는 것은 권장하지 않습니다.**
(각 Layer의 역할이 이미 표준으로 충분히 정리되어 있기 때문입니다.) ## Import 규칙[](#import-규칙 "해당 헤딩으로 이동") 각 Layer는 여러 개의 **Slice(서로 밀접하게 연관된 모듈 묶음)** 로 구성됩니다.
Slice들 사이의 연결은 **Layer Import 규칙**을 통해 제한합니다. > **규칙:**
하나의 Slice 안에서 작성된 코드는
**자신이 속한 Layer보다 아래 Layer**에 있는 *다른 Slice*만 import할 수 있습니다. 예를 들어, `📁 ~/features/aaa/api/request.ts` 파일은 다음과 같습니다. * 같은 Layer의 `📁 ~/features/bbb` → **import 불가능** * 더 아래 Layer(`📁 ~/entities`, `📁 ~/shared`) → **import 가능** * 같은 Slice(`📁 ~/features/aaa/lib/cache.ts`) → **import 가능** `app`과 `shared`는 조금 특이한 Layer입니다.
두 Layer는 **Layer이면서 동시에 하나의 큰 Slice처럼 동작**하고 내부 구조는 **Segment**로 나뉩니다. 이 경우에는 Layer 내부에서 Segment끼리는 자유롭게 import할 수 있습니다.
(`shared`는 비즈니스 도메인이 없고, `app`은 모든 도메인을 묶는 상위 조정자 역할을 합니다.) ## Layer별 역할[](#layer별-역할 "해당 헤딩으로 이동") 이제 각 Layer가 어떤 의미를 가지는지,
그리고 보통 어떤 종류의 코드가 해당 Layer에 들어오는지 정리해 보겠습니다. ### Shared[](#shared "해당 헤딩으로 이동") Shared Layer는 앱의 **기본 구성 요소와 기반 도구들을 모아두는 곳**입니다.
백엔드, 서드파티 라이브러리, 실행 환경과의 연결,
그리고 여러 곳에서 사용하는 **응집도 높은 내부 라이브러리**가 여기에 위치합니다. `app`과 마찬가지로 **Slice 없이 Segment로만 구성**합니다.
비즈니스 도메인이 없기 때문에, **Shared 내부의 파일들은 서로 자유롭게 import**할 수 있습니다. Segment 예시: * `📁 api` — API 클라이언트와 공통 백엔드 요청 함수 * `📁 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 "해당 헤딩으로 이동") Entities Layer는 프로젝트에서 다루는 **핵심 비즈니스 개념**을 표현합니다.
대부분의 경우, 실제 도메인 용어(예: `User`, `Post`, `Product`)와 일치합니다. 각 Entity Slice에는 다음과 같은 것들을 포함할 수 있습니다. 구성: * `📁 model` — 데이터 상태, 도메인 로직, 검증 스키마 * `📁 api` — 해당 Entity와 관련된 API 요청 * `📁 ui` — Entity의 시각적 표현 * 완성된 큰 UI 블록이 아니어도 됩니다. * 여러 페이지에서 재사용 가능한 형태로 설계합니다. * 비즈니스 로직은 가능하면 props/slot으로 외부에서 주입하는 방식을 권장합니다. #### Entity 간 관계[](#entity-간-관계 "해당 헤딩으로 이동") 원칙적으로는 Entity Slice끼리는 서로 **서로를 모르는 상태**가 이상적입니다.
하지만 실제 애플리케이션에서는 한 Entity가 다른 Entity를 **포함하거나**
여러 Entity가 서로 **상호작용**하는 일이 자주 발생합니다. 이런 경우, 두 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
보통 하나 이상의 Entity와 연관되어 동작합니다. * 모든 동작을 무조건 Feature로 만들 필요는 없습니다. * **여러 페이지에서 재사용되는 기능**일 때 Feature로 추출하는 것을 고려하세요. * 예: 여러 종류의 에디터에서 동일한 댓글 기능을 사용한다면, `comments`를 Feature로 만들 수 있습니다. * Feature가 너무 많아지면, 중요한 기능이 어디 있는지 찾기 어려워질 수 있습니다. 구성: * `📁 ui` — 상호작용 UI (예: 폼, 검색 바 등) * `📁 api` — 해당 기능과 직접 관련된 API 요청 * `📁 model` — 검증 로직, 내부 상태 관리 * `📁 config` — Feature Flag 등 기능별 설정 > 새로운 팀원이 프로젝트에 합류했을 때,
Page와 Feature만 훑어봐도 **이 앱이 어떤 기능을 제공하는지**를 대략 이해할 수 있도록 구성하는 것이 목표입니다. ### Widget[](#widget "해당 헤딩으로 이동") Widgets Layer는 **독립적으로 동작하는 비교적 큰 UI 블록**을 두는 곳입니다.
여러 페이지에서 재사용되거나, 한 페이지에서 **큰 섹션 단위로 나누어지는 UI 블록**이 있을 때 유용합니다. tip 재사용되지 않고 특정 페이지의 핵심 콘텐츠에만 쓰인다면, 굳이 Widget으로 분리하지 말고 Page 내부에 두는 것이 좋습니다.
Nested Routing(예: [Remix](https://remix.run)) 환경에서는 Widget이 **Page와 비슷한 역할**을 할 수 있습니다.
예를 들어 데이터 로딩, 로딩 상태 표시, 에러 처리 등을 모두 포함하는 **하나의 라우터 단위 UI 블록**으로 동작할 수 있습니다. ### Page[](#page "해당 헤딩으로 이동") Pages Layer는 웹/앱에서 보이는 **화면(screen) 또는 액티비티(activity)** 에 해당합니다.
일반적으로 “페이지 1개 = Slice 1개” 구조를 많이 사용하지만,
구조가 유사한 페이지들은 하나의 Slice로 묶는 것도 가능합니다. 코드를 찾기만 쉽다면, Page Slice의 크기에 특별한 제한은 없습니다.
재사용되지 않는 UI는 그대로 Page 내부에 두면 됩니다.
Page Layer에는 보통 전용 model이 없으며, 필요한 경우 간단한 상태만 컴포넌트 내부에서 관리합니다. 구성 예: * `📁 ui` — 페이지 UI, 로딩 상태, 에러 상태 처리 * `📁 api` — 페이지에서 사용하는 데이터 패칭/변경 요청 ### Process[](#process "해당 헤딩으로 이동") caution **Deprecated** — 기존에 사용하던 코드는 가능하면 Feature나 App Layer로 이동하세요. 과거에는 여러 페이지를 넘나드는 복잡한 기능을 처리하기 위한 **탈출구 같은 Layer**로 사용되었습니다.
하지만 역할이 모호하고, 대부분의 애플리케이션에서는 굳이 사용하지 않아도 충분히 설계가 가능합니다. 라우터, 서버 연동 같은 전역적인 로직은 보통 App Layer에 둡니다.
App Layer가 너무 복잡해질 때 정말 필요한 경우에만 제한적으로 고려할 수 있습니다. ### App[](#app "해당 헤딩으로 이동") App Layer는 앱 전역에서 동작하는 **환경 설정**과 **공용 로직**을 관리하는 곳입니다.
예를 들어 라우터 설정, 전역 상태 관리(Store 설정), 글로벌 스타일 앱 진입점(Entry Point) 설정 등과 같이
**앱 전체에 영향을 주는 코드**가 위치합니다.
`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` 파일에서 `LoginPage`, `RegisterPage` 등을 다시 내보내는 방식입니다. 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의 인터페이스를 흐리게 만들고, 나중에 큰 부담이 됩니다. 예를 들어 `features/comments/index.js`에서 `./ui/Comment` 전체를 그대로 export 하거나
`./model/comments` 내부 모델을 통째로 export 하는 식입니다. Bad practice, features/comments/index.js ``` // ❌ 이렇게 하지 마세요 export * from "./ui/Comment"; // 👎 무분별한 UI export export * from "./model/comments"; // 💩 내부 모델 노출 ``` 이 방식이 문제가 되는 이유: * **발견 가능성 저하** * Public API에서 어떤 기능을 제공하는지 한눈에 파악하기 어렵습니다. * **내부 구현 노출** * 원래 외부에서 알 필요가 없는 내부 코드를 외부에서 직접 사용하게 되고,
이 코드에 대한 의존성이 생기면 리팩터링이 매우 어려워집니다. ## Cross-Import를 위한 Public API[](#public-api-for-cross-imports "해당 헤딩으로 이동") **Cross-import**는 같은 Layer 안에서 한 Slice가 다른 Slice를 import하는 것을 말합니다.
[Layer Import Rule](/kr/docs/reference/layers.md#import-rule-on-layers)에 따라 원칙적으로는 금지되지만,
**Entity 간 참조**처럼 현실적으로 불가피한 경우가 있습니다. 예를 들어, 도메인 모델에서 `Artist`와 `Song`이 서로 연관 관계를 가진다면
이를 억지로 숨기기보다는 코드에도 그 관계를 드러내는 편이 낫습니다. 이럴 때는 `@x` 표기를 사용해 **교차 참조 전용 Public API**를 명시적으로 만듭니다. 폴더 예시: ``` - 📂 entities - 📂 artist - 📂 @x - song.ts — entities/song 전용 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(`pages/home/index.js`)에서 `HomePage`와 `loadUserStatistics`를 export합니다.  위 그림: `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"; ``` `HomePage` 컴포넌트(`HomePage.jsx`)는 다시 Public API를 통해 `loadUserStatistics`를 import합니다. 이 경우 의존 관계는 다음과 같이 순환합니다. * `index.js` → `HomePage.jsx` → 다시 `index.js` 이렇게 되면, 빌드 시점이나 런타임 시점에 예측하기 어려운 문제가 생길 수 있습니다. #### 예방 원칙[](#예방-원칙 "해당 헤딩으로 이동") * **같은 Slice 내부**에서 가져올 때는 * 상대 경로(`../api/loadUserStatistics`)를 사용해서 * 어느 파일을 참조하는지 명확히 작성합니다. * **다른 Slice**에서 가져올 때는 * 절대 경로(예: `@/features/...`)나 Alias를 사용합니다. * Index에서 export한 모듈이 다시 Index를 참조하지 않도록 주의합니다. ### Large Bundle & Tree-shaking 문제[](#large-bundles "해당 헤딩으로 이동") 일부 Bundler는 Index 파일에서 여러 모듈을 한 번에 export할 경우,
실제로 사용하지 않는 코드(Dead code)를 제대로 제거(Tree-shaking)하지 못할 수 있습니다. 대부분의 Public API에서는 모듈 간 연관성이 높아 크게 문제되지 않지만,
`shared/ui`, `shared/lib`처럼 **서로 관련성이 낮은 모듈 묶음**에서는 문제가 커집니다. 예시 구조: ``` - 📂 shared/ui/ - 📂 button - 📂 text-field - 📂 carousel - 📂 accordion ``` 이 상황에서 단순히 `Button` 하나만 사용하고 싶어도,
만약 `shared/ui` 전체를 통째로 export하는 큰 Index가 있다면 * `carousel`, `accordion` 등 무거운 의존성까지 * 함께 번들에 포함될 수 있습니다. 특히 Syntax Highlighter, Drag-and-Drop 라이브러리처럼
용량이 큰 의존성은 최종 번들 크기에 큰 영향을 줍니다. #### 해결 방법[](#해결-방법 "해당 헤딩으로 이동") 각 컴포넌트/라이브러리별로 **별도의 작은 Index 파일**을 만듭니다. 예시: ``` - 📂 shared/ui/ - 📂 button - index.ts - 📂 text-field - index.ts ``` 그리고 사용하는 쪽에서는 `@/shared/ui/button`, `@/shared/ui/text-field`와 같이 **컴포넌트 단위로 직접 import**합니다. pages/sign-in/ui/SignInPage.jsx ``` import { Button } from "@/shared/ui/button"; import { TextField } from "@/shared/ui/text-field"; ``` 이렇게 하면 Bundler가 사용되지 않는 컴포넌트 코드를 제거할 수 있어 Tree-shaking이 더 잘 동작하게 됩니다. ### Public API 우회 방지의 한계[](#public-api-우회-방지의-한계 "해당 헤딩으로 이동") Slice에 Index 파일을 만들어도, 개발자가 직접 내부 경로를 입력해 import하는 것을 완전히 막을 수는 없습니다. 특히 IDE의 Auto Import 기능이 내부 파일 경로를 자동으로 선택해 버리면, Public API 규칙을 모르는 상태에서 내부 구현을 바로 import하게 될 수 있습니다. #### 해결 방법[](#해결-방법-1 "해당 헤딩으로 이동") * [Steiger](https://github.com/feature-sliced/steiger) 같은 **FSD 전용 아키텍처 린터**를 사용해 프로젝트의 import 경로를 검사하고, 규칙을 강제합니다. ## 대규모 프로젝트에서의 Bundler 성능 문제[](#대규모-프로젝트에서의-bundler-성능-문제 "해당 헤딩으로 이동") [TkDodo 글](https://tkdodo.eu/blog/please-stop-using-barrel-files)에서도 언급되듯,
Index 파일(일명 **barrel 파일**)이 너무 많아지면 개발 서버 실행 속도나 HMR(Hot Module Replacement) 성능이 저하될 수 있습니다. #### 최적화 방법[](#최적화-방법 "해당 헤딩으로 이동") 1. [Large Bundle & Tree-shaking 문제](#large-bundles)에서 설명한 것처럼, `shared/ui`, `shared/lib`에 있는 큰 Index를 없애고 컴포넌트/모듈 단위로 쪼갠 작은 Index를 사용합니다. 2. Segment 단위로 불필요한 Index 파일을 만들지 않습니다. * 예: `features/comments/index.ts`가 이미 Slice의 Public API 역할을 하고 있다면, `features/comments/ui/index.ts` 같이 중첩된 Index는 굳이 만들 필요가 없습니다. 3. 큰 프로젝트는 **기능 단위 Chunk 또는 패키지**로 나눕니다. * 예: Google Docs처럼 Document Editor와 File Browser를 서로 다른 Chunk/패키지로 분리 * 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` Layer와 `App` Layer는 Slice를 가지지 않습니다. * `Shared` Layer는 비즈니스 로직이 전혀 없으므로, 제품 관점에서 Slice로 나눌 의미가 없습니다. * `App` Layer는 애플리케이션 전체를 다루기 때문에, 여기서 다시 Slice로 나눌 필요가 없습니다. ### 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](/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 페이지](/kr/docs/reference/layers.md#layer-definitions)에서 자세히 설명합니다. 또한 프로젝트에 맞게 **커스텀 Segment**를 정의할 수도 있습니다.
특히 `App` Layer와 `Shared` Layer는 Slice가 없기 때문에,
이 두 Layer에서는 커스텀 Segment를 자주 사용하게 됩니다. Segment 이름을 정할 때는,
폴더 안에 **무슨 파일이 들어 있는지**가 아니라 **무엇을 위해 존재하는지(목적)** 가 드러나도록 작성하는 것이 좋습니다. 예를 들어 `components`, `hooks`, `types` 같은 이름은 성격만 나타낼 뿐,
**역할이나 목적을 알기 어렵기 때문에** 가능한 한 피하는 편이 좋습니다. --- ### 명시적 비즈니스 로직 도메인별로 코드를 구분해 필요한 로직을 즉시 찾을 수 있습니다. ---