Apply Feature-Sliced Design (FSD) v2.1 architectural methodology to frontend projects. Use when organizing code structure, decomposing features, creating new components or features, refactoring existing codebases, or when users mention "FSD", "Feature-Sliced", layers, slices, or frontend architecture patterns.
Apply Feature-Sliced Design (FSD) v2.1 architectural methodology to frontend projects. Use when organizing code structure, decomposing features, creating new components or features, refactoring existing codebases, or when users mention "FSD", "Feature-Sliced", layers, slices, or frontend architecture patterns.
Feature-Sliced Design (FSD) Skill - v2.1.0
An architectural methodology skill for scaffolding and organizing frontend applications using Feature-Sliced Design principles.
Overview
Feature-Sliced Design v2.1 is a compilation of rules and conventions for organizing frontend code to make projects more understandable, maintainable, and stable in the face of changing business requirements.
Version 2.1 introduces the "Pages First" approach - keeping more code in pages and widgets rather than prematurely extracting it to features and entities.
Core Principles
The "Pages First" Approach (FSD v2.1)
The fundamental principle of FSD v2.1: Keep code where it's used until you need to reuse it.
Instead of immediately extracting everything into entities and features, start by keeping code in pages and widgets. Only move code to lower layers when you actually need to reuse it.
What stays in Pages and Widgets:
✅ Large UI blocks that are only used on one page
✅ Forms and their validation logic specific to a page
✅ Data fetching and state management for page-specific data
✅ Business logic that serves only this page/widget
✅ API interactions needed only here
When to extract to lower layers:
To Shared: When you need the same infrastructure in multiple places (modal manager, date formatter, UI components)
To Entities: When you have a clear business domain model that's used across multiple features
To Features: When you have a complete user interaction that's reused in multiple places
Why "Pages First"?
Better code cohesion - related code stays together
Easier to delete - unused code is right there with its usage
Less abstraction overhead - no need to identify entities/features prematurely
Natural decomposition - pages are intuitive to understand
Faster development - no time wasted on premature optimization
1. Layered Architecture (Vertical Organization)
FSD uses 6 active standardized layers organized by responsibility and dependencies. Layers are ordered from most specific (top) to most generic (bottom):
app/ ← Application initialization, providers, global styles
pages/ ← Full page compositions with their own logic, routing
widgets/ ← Large composite UI blocks with their own logic
features/ ← Reusable user interactions and business features
entities/ ← Reusable business entities (user, product, order)
shared/ ← Reusable infrastructure code (UI kit, utils, API)
Note: Historically, FSD included processes/ as a 7th layer, but it is deprecated in v2.1. If you're using it, move the code to features/ with help from app/ if needed.
Import Rule: A module can only import from layers strictly below it.
Slices group code by business domain meaning. Each slice represents a specific business concept:
features/
├── auth/ ← Authentication feature
├── comments/ ← Comments functionality
└── post-editor/ ← Post editing feature
entities/
├── user/ ← User business entity
├── product/ ← Product business entity
└── order/ ← Order business entity
Key Rules:
Slices must be independent from other slices on the same layer (zero coupling)
Slices should contain most code related to their primary goal (high cohesion)
Slice names are not standardized - they reflect your business domain
3. Segments (Technical Organization)
Segments group code within slices by technical purpose:
features/
└── auth/
├── ui/ ← React components, styles, formatters
├── api/ ← API requests, data types, mappers
├── model/ ← State management, business logic, stores
├── lib/ ← Internal utilities for this slice
├── config/ ← Configuration, feature flags
└── index.ts ← Public API (exports only what other slices need)
Standard Segments:
ui - UI components, styles, date formatters
api - Backend interactions, request functions, data types
model - Data models, state stores, business logic
lib - Utility functions needed by this slice
config - Configuration files, feature flags
4. Public API
Every slice must define a public API through an index file:
// features/auth/index.tsexport { LoginForm } from'./ui/LoginForm';
export { useAuth } from'./model/useAuth';
export { loginUser } from'./api/loginUser';
// Internal files not exported remain private to the slice
Rule: Modules outside a slice can only import from the public API, not from internal files.
Public API for Cross-Imports (@x notation)
New in v2.1: You can now create explicit connections between slices on the same layer (typically entities) using the @x notation.
This allows entities to reference each other when there's a legitimate business relationship:
// entities/user/index.tsexport { UserCard } from'./ui/UserCard';
export { userModel } from'./model';
// entities/user/@x/order.ts// Cross-import API specifically for the order entityexport { UserOrderHistory } from'./ui/UserOrderHistory';
export { getUserOrders } from'./api/getUserOrders';
// entities/order/index.tsimport { UserOrderHistory } from'@/entities/user/@x/order';
// Now order can import from user's cross-import API
When to use cross-imports:
There's a clear business relationship between entities (e.g., User and Order)
The dependency is bidirectional or circular in the business domain
You want to keep the code together while acknowledging the relationship
Important: Regular cross-imports between slices (without @x) are still not allowed. Use @x notation to make cross-dependencies explicit and controlled.
If you have an existing FSD 2.0 project, migration to 2.1 is non-breaking. You can adopt the "pages first" approach gradually.
Migration Steps:
Audit current features and entities
Which features/entities are used in only one place?
Mark them for potential moving to pages/widgets
Move page-specific code back to pages
Forms used on one page → pages/[page]/ui/
Page-specific API calls → pages/[page]/api/
Page-specific state → pages/[page]/model/
Move widget-specific code to widgets
Logic only used in one widget → keep in that widget
Don't extract to features prematurely
Keep truly reusable code in features/entities
Used in 2+ places → stays in features/entities
Clear business value → stays in features/entities
Update Shared with application-aware code
Move route constants → shared/api/routes.ts
Move company assets → shared/assets/
Keep it free of business logic
Deprecate Processes layer
Move code to features/ with help from app/ if needed
Consider using @x notation
For entities with bidirectional relationships
Makes cross-dependencies explicit
Example Migration:
Before (v2.0):
features/
└── user-profile-form/ ← Only used on profile page
├── ui/
├── model/
└── api/
pages/
└── profile/
└── ui/
└── ProfilePage.tsx ← Just composition
After (v2.1):
pages/
└── profile/
├── ui/
│ ├── ProfilePage.tsx
│ └── ProfileForm.tsx ← Moved here
├── model/
│ └── profileStore.ts ← Moved here
└── api/
└── updateProfile.ts ← Moved here
Migration Strategy
When migrating existing code to FSD:
Start with Shared: Move UI kit, utils, API client to shared/
Identify Entities: Extract business domain models to entities/
Extract Features: Isolate user interactions to features/
Create Pages: Compose pages from widgets and features
Setup App: Move global providers and routing to app/
Do it gradually - you don't need to refactor everything at once.
Extract to features/entities only when you see actual reuse
Setup providers and routing in app/
Add public API (index.ts) to each slice
Configure Steiger linter for FSD rules (recommended)
Document architecture decisions for team
Steiger - Architectural Linter for FSD
Steiger is an official linter that helps enforce FSD rules automatically:
✅ Detects import rule violations
✅ Checks public API usage
✅ Identifies cross-imports between slices
✅ Ensures proper layer structure
✅ Provides actionable error messages
Installation:
npm install -D @feature-sliced/steiger
Usage:
npx steiger src
Steiger is production-ready and actively maintained. It's the best way to ensure your team follows FSD conventions consistently.
When to Use This Skill
Trigger this skill when:
User mentions "FSD", "Feature-Sliced Design", "feature sliced"
Creating new frontend project structure
Refactoring existing frontend codebase
Discussing code organization or architecture
Questions about where to put specific code
Issues with cross-imports or dependencies
Need to decompose features or components
Setting up project structure for React/Vue/Angular/Svelte
Migrating from FSD v2.0 to v2.1
Core Philosophy of FSD v2.1
"Start simple, extract when needed."
Don't try to predict the future architecture. Build features in pages and widgets first. When you see actual reuse patterns emerging, then extract to features and entities. This leads to:
This skill provides the foundational knowledge to structure any frontend application using Feature-Sliced Design v2.1 methodology. Always prioritize code cohesion, wait for actual reuse before extracting, and maintain proper layering to ensure maintainable and scalable code architecture.
