Feature-Sliced Design (FSD) v2.1

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

1. Core Philosophy & Layer Overview

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

Place code in pages/ first. Duplication across pages is acceptable and does not automatically require extraction to a lower layer. Extract only when the same code is currently being used in multiple places (not hypothetically), the usages do not always change together, and the boundary has a focused responsibility.

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

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/   → Large composite UI blocks reused across multiple pages
features/  → Reusable user interactions (only when used in 2+ places)
entities/  → Reusable business domain models (only when used in 2+ places)
shared/    → Infrastructure with no business logic (UI kit, utils, API client)

Import rule: A module may only import from layers strictly below it. Cross-imports between slices on the same layer are forbidden.

// ✅ 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 used in only one page → keep it in that page (Steiger: insignificant-slice).

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

• UI components → shared/ui/
• Utility functions → shared/lib/
• API client, route constants → shared/api/ or shared/config/
• Auth tokens, session management → shared/auth/
• CRUD operations → shared/api/

Step 3: Is it a complete user action currently used in multiple places, with stable boundaries?

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

Step 4: Is it a business domain model currently used in multiple places, with stable boundaries?

• 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 same code is actively used in multiple places and the boundary is clear.

3. Quick Placement Table

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 and cross-imports between slices on the same layer are forbidden.

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.

RSC / meta-framework exception: Split entry points (index.client.ts, index.server.ts) are permitted. Details and rules: 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. Do not create direct imports.

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

Name files after the business domain they represent, not their technical role. Technical-role names like types.ts, utils.ts, helpers.ts mix unrelated domains in a single file and reduce cohesion.

// ❌ Technical-role naming
model/types.ts          ← Which types? User? Order? Mixed?
model/utils.ts

// ✅ 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.

// ❌ Business logic in shared
// shared/lib/userHelpers.ts
export const calculateUserReputation = (user) => { ... };

// ✅ Move to the owning domain
// entities/user/lib/reputation.ts
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/. When the same user data is being consumed by another page (not hypothetically), extract the shared model to entities/user/. 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 e