Feature Sliced Design

Feature-Sliced Design (FSD) v2.1

Source: fsd.how | Strictness can be adjusted based on project scale and team context.

How to use this skill. For placement decisions, start with the decision tree in Section 2 and use the placement table in Section 3 as a quick reference. To check a structure for violations, use the rules in Section 4. To resolve same-layer cross-imports, use Section 7. For task-specific guidance, load only the relevant reference files from Section 10; do not preload the rest.

1. Core philosophy & layer overview

FSD v2.1 core principle: "Start simple, extract when needed."

The extraction rule

Place code in pages/ first. Duplication across pages is acceptable and does not by itself require extraction to a lower layer. Extract only when all three conditions hold:

1. The same code is used in multiple places right now, not hypothetically.
2. It has a reason to change that is independent of any one consumer.
3. The boundary has a focused responsibility.

The six layers

Not all layers are required. Most projects can start with only shared/, pages/, and app/. Add features/ and entities/ only when they provide clear value. Do not create empty layer folders "just in case." The widgets/ layer is discouraged (see the callout below).

FSD uses 6 standardized layers, listed here from highest to lowest:

app/       → App initialization, providers, routing
pages/     → Route-level composition, owns its own logic
widgets/   → Reusable UI blocks (discouraged, see the callout below)
features/  → Reusable user interactions (see the extraction rule above)
entities/  → Reusable business domain models (see the extraction rule above)
shared/    → Infrastructure with no business logic (UI kit, utils, API client)

The official layer reference discourages using the Widgets layer, and this skill follows it. Widgets may seem useful for representing independent UI blocks. However, in real frontend code, UI blocks often include logic required for user flows, such as data fetching, state management, and event handling. In this case, the responsibilities of Features, which handle user flows, and Widgets, which handle UI blocks, can overlap, making the boundary between the two layers unclear.

Not creating a widget does not mean moving the block elsewhere untouched. A screen-specific composition stays in pages; a reused action and the UI to perform it go to features; context-free UI goes to shared; an app-wide layout goes to app.

Discouraged is not deprecated: an existing widgets layer stays valid. See references/layer-structure.md for that case and for layout placement.

The import rule

A module may only import from layers strictly below it. Cross-imports between slices on the same layer are forbidden, with one narrow exception in Section 7.

// Allowed
import { Button } from "@/shared/ui/Button"; // features → shared
import { useUser } from "@/entities/user"; // pages → entities

// Violation
import { loginUser } from "@/features/auth"; // entities → features
import { likePost } from "@/features/like-post"; // features → features

Note: The processes/ layer is deprecated in v2.1. For migration details, read references/migration-guide.md.

2. Decision framework

When writing new code, follow this tree:

Step 1: Where is this code used?

• Used in only one page → keep it in that pages/ slice.
• Used in 2+ pages but duplication is manageable → keeping separate copies in each page is also valid.
• An entity or feature with a single consumer → keep it at the consumer (Steiger flags this as insignificant-slice).

Step 2: Is it reusable infrastructure with no business logic?

The official layer reference draws the line for Shared like this: no business logic, but business-themed is fine (a company logo, a page layout), and so is UI logic (autocomplete, a search bar). Exchanging data with the backend and CRUD boilerplate are not business logic either. Business logic is a rule the product enforces on its own data, such as applying a discount to an order. If the code fits none of the exclusions and still does not clearly enforce a product rule, the term does not decide; go back to Step 1 and place it by where it is used.

• UI components → shared/ui/
• Utility functions → shared/lib/
• API client, route constants → shared/api/ or shared/config/
• Auth tokens, session management → shared/auth/
• CRUD once several slices call it → shared/api/ (a single caller keeps it, see Step 1)

Step 3: Is it a complete user action that several consumers share, with a focused responsibility and a reason to change of its own?

• Yes → features/
• Uncertain, single use, or speculative reuse → keep in the page.

Step 4: Is it a business domain model that several consumers share, with a focused responsibility and a reason to change of its own?

• Yes → entities/
• Uncertain, single use, or speculative reuse → keep in the page.

Step 5: Is it app-wide configuration?

• Global providers, router, theme → app/

Golden Rule: When in doubt, keep it in pages/. Extract only when the extraction rule holds.

3. Quick placement table

Scenario	Single use	Confirmed multi-use
User profile form	pages/profile/ui/ProfileForm.tsx	features/profile-form/
Product card	pages/products/ui/ProductCard.tsx	entities/product/ui/ if the entity owns it
API request (read or CRUD)	pages/product-detail/api/fetch-product.ts	shared/api/ (no domain rules)
Auth token/session	shared/auth/	shared/auth/
Auth login form	pages/login/ui/LoginForm.tsx	features/auth/
Generic Card layout		shared/ui/Card/
Modal manager		shared/ui/modal-manager/
Modal content	pages/[page]/ui/SomeModal.tsx
Date formatting util		shared/lib/format-date.ts

"Confirmed multi-use" means the extraction rule holds, not that a second consumer appeared: two similar copies that keep drifting apart stay in their pages (references/growth-walkthrough.md, Snapshot 1). Entity UI carries the Section 6 caution even when the rule does hold.

4. Architectural rules (MUST)

These rules are the foundation of FSD. Violations weaken the architecture. If you must break a rule, ensure it is an intentional design decision and document the reason in code (a comment or ADR).

4-1. Import only from lower layers

app → pages → widgets → features → entities → shared. Upward imports are forbidden. So are cross-imports between slices on the same layer, except through the other slice's public API as a last resort (Section 7, Strategy D).

4-2. Public API: every slice exports through index.ts

External consumers may only import from a slice's index.ts. Direct imports of internal files are forbidden.

// Correct
import { LoginForm } from "@/features/auth";

// Violation: bypasses public API
import { LoginForm } from "@/features/auth/ui/LoginForm";

Shared layer: Shared has no slices. Define a separate public API per segment (shared/ui/index.ts, shared/api/index.ts, etc.) rather than one top-level shared/index.ts. This keeps imports from Shared organized by intent.

Where one index over a segment's unrelated modules hurts bundling, give each component, library, or controller folder its own index instead (shared/ui/Button/index.ts as @/shared/ui/Button, shared/api/post/ as @/shared/api/post). That folder is then the boundary; reaching past it (@/shared/ui/Button/Button.tsx) is still a violation. See references/layer-structure.md for the shape.

Environment-specific entry points: a slice normally exposes one index.ts, and ad-hoc variations are not recommended. If a single index cannot preserve a runtime boundary, add an entry point such as index.server.ts. See references/framework-integration.md.

4-3. No cross-imports between slices on the same layer

If two slices on the same layer need to share logic, follow the resolution order in Section 7. Never reach into another slice's internals.

4-4. Domain-based file naming (no desegmentation)

Name files after what they are for, the domain or concern they serve, not after their technical role. Technical-role names like types.ts, utils.ts, helpers.ts mix unrelated concerns in a single file and reduce cohesion.

// BAD: technical-role naming
model/types.ts          ← Which types? User? Order? Mixed?
model/utils.ts

// GOOD: domain-based naming
model/user.ts           ← User types + related logic
model/order.ts          ← Order types + related logic
api/fetch-profile.ts    ← Clear purpose

4-5. No business logic in shared/

Shared contains only infrastructure: UI kit, utilities, API client setup, route constants, assets. Business calculations, domain rules, and workflows belong in entities/ or higher layers. Section 2, Step 2 says what counts.

// BAD: business logic in shared
// shared/lib/userHelpers.ts
export const calculateUserReputation = (user) => { ... };

// GOOD: move it to whoever owns the rule
// pages/profile/model/reputation.ts       ← while the profile page owns it
// entities/user/model/reputation.ts       ← once a user boundary is earned
export const calculateUserReputation = (user) => { ... };

5. Recommendations (SHOULD)

5-1. Pages first: place code where it is used

Place code in pages/ first. Extract to lower layers only when truly needed. Extraction is a design decision that affects the whole project, so the threshold should be high.

What stays in pages:

• Large UI blocks used only in one page
• Page-specific forms, validation, data fetching, state management
• Page-specific business logic and API integrations
• Code that looks reusable but is simpler to keep local

Evolution pattern: Start with everything in pages/profile/. Extract the shared model to entities/user/ when a second page consumes it and the extraction rule holds. A response type that several pages read is not one of those cases: it stays in shared/api. Keep page-specific API calls and UI in the page.

5-2. Be conservative with entities

The entities layer is highly accessible (almost every other layer can import from it), so changes propagate widely.

1. Start without entities. shared/ + pages/ + app/ is valid FSD. Thin-client apps rarely need entities.
2. Do not split slices prematurely. Keep code in pages. Extract to entities only when the extraction rule holds.
3. Business logic does not automatically require an entity. Keeping types in shared/api and logic in the current slice's model/ segment may be sufficient.
4. CRUD is infrastructure, not entities. Place it by the request placement rule: with its consumer while there is one, in shared/api/ once several slices call it.
5. Place auth data in shared/auth/ or shared/api/. Tokens and login DTOs are auth-context-dependent and rarely reused outside authentication.

For detailed guidance on keeping the entities layer clean (when to skip it entirely, how to isolate business contexts, why CRUD belongs in shared/api), see references/excessive-entities.md.

5-3. Start with minimal layers

// Valid minimal FSD project
src/
  app/         ← Providers, routing
  pages/       ← All page-level code
  shared/      ← UI kit, utils, API client

// Add layers only when an actual use case requires them:
// + features/  ← User-action boundaries that need one shared home
// + entities/  ← Domain boundaries that need one shared home
// (widgets/ is discouraged; see Section 1 for where that code goes instead)

5-4. Validate with the Steiger linter

Steiger is the official FSD linter. Key rules:

• insignificant-slice: Flags a slice with no references, or with one, and suggests merging it into the layer above. Pages may hold a single reference, and so may slices used only from app/.
• excessive-slicing: Suggests merging or grouping when a layer has too many slices.

npm install -D @feature-sliced/steiger
npx steiger src

6. Anti-patterns (AVOID)