Feature-Sliced Design Architecture

Frontend architecture methodology (spec v2.1) with a strict layer hierarchy and one import rule. FSD organizes code by business domain rather than technical role.

Official Docs: feature-sliced.design | GitHub: feature-sliced

THE IMPORT RULE (Critical)

A module in a slice may only import slices from layers strictly below. Never sideways or upward. This is what keeps slices replaceable and dependencies traceable — every violation you allow becomes an invisible coupling someone else trips over.

app → pages → widgets → features → entities → shared
 ↓      ↓        ↓          ↓          ↓         ✓
 ✓      ✓        ✓          ✓          ✓      (external only)

Exception: app/ and shared/ are each "a layer and a slice at the same time" — they divide directly into segments, and their segments may freely import each other.

Layer Hierarchy

The processes/ layer is deprecated — move its contents to features/ and app/.

Minimal setup: app/, pages/, shared/. A small app with 5 routes does not need entities, features, or widgets — adding them "for completeness" spreads single-use code across the tree and negates FSD's cohesion benefit. Add a layer only when something is genuinely reused by 2+ pages.

Pages First (v2.1 default)

When unsure where code goes, put it in the page slice that uses it — including forms, data logic, and large UI blocks. Extract downward only when a second page needs it. Why: page-local code is found instantly by newcomers; premature entities/features force jumping through several folders to change one user flow.

Where does this code go?
├─ Used by exactly ONE page              → that page's slice (even logic/forms)
├─ App-wide config, providers, routing   → app/
├─ Domain-agnostic or infra code         → shared/
├─ Reused across pages:
│  ├─ Large UI block with own logic      → widgets/
│  ├─ User action (verb)                 → features/
│  └─ Domain model/data (noun)           → entities/

"Feature or Entity?"

Entities represent THINGS with identity. Features represent ACTIONS with side effects. Not everything is a feature — an interaction used on one page stays in that page.

"Which segment?"

Segments divide a slice by technical purpose:

├─ ui/      → components, styles, formatters
├─ api/     → backend calls, DTOs, mappers
├─ model/   → types, schemas, stores, business logic
├─ lib/     → slice-internal utilities
└─ config/  → feature flags, constants

Name segments by purpose, not essence: api/, model/, lib/ — never hooks/, components/, types/, utils/. Purpose names tell a reader what the code is for; essence names just restate the file extension.

Directory Structure

src/
├── app/                    # Layer + slice: segments only
│   ├── providers/          # React context, QueryClient, theme
│   ├── routes/             # Router configuration
│   └── styles/             # Global CSS, theme tokens
├── pages/
│   └── {page-name}/
│       ├── ui/             # Page component + page-local blocks
│       ├── api/            # Loaders, server actions
│       ├── model/          # Page-specific state
│       └── index.ts        # Public API
├── widgets/
│   └── {widget-name}/
│       ├── ui/
│       ├── api/            # Widgets may fetch their own data (v2.1)
│       └── index.ts
├── features/
│   └── {feature-name}/
│       ├── ui/
│       ├── api/
│       ├── model/
│       └── index.ts
├── entities/
│   └── {entity-name}/
│       ├── ui/             # Entity UI (Card, Avatar)
│       ├── api/            # CRUD operations
│       ├── model/          # Types, mappers, validation
│       └── index.ts
└── shared/                 # Layer + slice: segments only, no root index
    ├── ui/                 # Design system (index per component)
    ├── api/                # API client, interceptors
    ├── lib/                # Utilities (dates, validation)
    ├── config/             # Environment, constants
    ├── routes/             # Route path constants
    └── i18n/               # Translations

Public API Pattern

Every slice exposes ONE public API via index.ts. External code imports only from it — the index is the contract that lets a slice refactor its internals freely.

// entities/user/index.ts
export { UserCard } from './ui/UserCard';
export { getUser, updateUser } from './api/userApi';
export type { User, UserRole } from './model/types';

// ✅ Correct
import { UserCard, type User } from '@/entities/user';

// ❌ Wrong — reaches into internals
import { UserCard } from '@/entities/user/ui/UserCard';

Three rules that prevent the common failure modes:

1. Explicit named exports, no wildcards. export * from './ui' hides the contract, leaks internals, and harms tree-shaking.
2. No segment-level index files on sliced layers. If features/comments/index.ts exists, don't also create features/comments/ui/index.ts — extra barrels slow bundlers and invite circular imports. Inside a slice, use relative imports; never import your own index.ts.
3. On shared/, the public API lives per segment (shared/api/index.ts), and for shared/ui/shared/lib, per component (shared/ui/button/index.ts) — one giant barrel bundles a syntax highlighter into every page.

Details and edge cases: [references/PUBLIC-API.md](references/PUBLIC-API.md).

Cross-Entity References (@x Notation)

Entities sometimes genuinely contain each other (an order contains products). Instead of a hidden cross-import, make it explicit with @x — used only on the entities layer:

entities/
├── product/
│   ├── @x/
│   │   └── order.ts    # exports intended specifically for the order entity
│   └── index.ts
└── order/
    └── model/types.ts  # imports from product/@x/order

// entities/product/@x/order.ts
export type { ProductId } from '../model/types';

// entities/order/model/types.ts
import type { ProductId } from '@/entities/product/@x/order';

Keep @x files tiny (usually type re-exports). If two entities cross-reference extensively, merge them.

Anti-Patterns

Tooling

Verify architecture automatically with Steiger, the official FSD linter:

npm i -D steiger @feature-sliced/steiger-plugin
npx steiger ./src            # add --watch during refactors

It catches cross-imports, missing public APIs, and single-use slices (fsd/insignificant-slice). ESLint alternative: @feature-sliced/eslint-config.

Path alias (required for @/entities/user-style imports):

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["./src/*"] }
  }
}

Reference Documentation

Resources

• Official documentation: https://feature-sliced.design
• Specification: https://feature-sliced.design/docs/reference
• GitHub organization: https://github.com/feature-sliced
• Examples: https://github.com/feature-sliced/examples
• Steiger linter: https://github.com/feature-sliced/steiger
• Awesome FSD: https://github.com/feature-sliced/awesome