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.
- ✅
features/ → entities/, shared/
- ✅
pages/ → widgets/, features/, entities/, shared/
- ❌
entities/ → features/ (upward import)
- ❌
features/comments/ → features/posts/ (same-layer cross-import)
2. Slices (Horizontal Organization)
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 formattersapi - Backend interactions, request functions, data typesmodel - Data models, state stores, business logiclib - Utility functions needed by this sliceconfig - Configuration files, feature flags
4. Public API
Every slice must define a public API through an index file:
export { LoginForm } from './ui/LoginForm';
export { useAuth } from './model/useAuth';
export { loginUser } from './api/loginUser';
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:
export { UserCard } from './ui/UserCard';
export { userModel } from './model';
export { UserOrderHistory } from './ui/UserOrderHistory';
export { getUserOrders } from './api/getUserOrders';
import { UserOrderHistory } from '@/entities/user/@x/order';
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.
Layer Definitions & Examples
App Layer
Application-wide settings, providers, routing setup.
app/
├── providers/ ← Redux Provider, React Query, Theme Provider
├── styles/ ← Global CSS, resets, theme variables
├── index.tsx ← Application entry point
└── router.tsx ← Route configuration
Pages Layer
Route-level compositions with their own logic and data management.
pages/
├── home/
│ ├── ui/
│ │ ├── HomePage.tsx
│ │ ├── HeroSection.tsx ← Large UI blocks
│ │ └── FeaturesGrid.tsx
│ ├── model/
│ │ └── useHomeData.ts ← Page-specific state
│ ├── api/
│ │ └── fetchHomeData.ts ← Page-specific API
│ └── index.ts
├── profile/
│ ├── ui/
│ │ ├── ProfilePage.tsx
│ │ ├── ProfileForm.tsx ← Forms specific to this page
│ │ └── ProfileStats.tsx
│ ├── model/
│ │ ├── profileStore.ts ← State for profile page
│ │ └── validation.ts ← Form validation
│ ├── api/
│ │ ├── updateProfile.ts
│ │ └── fetchProfile.ts
│ └── index.ts
└── settings/
v2.1 Approach: Pages can now contain:
- ✅ Large UI blocks used only on this page
- ✅ Forms and their validation logic
- ✅ Data fetching and state management
- ✅ Business logic that serves only this page
- ✅ API interactions specific to this page
Only extract to lower layers when you need to reuse the code elsewhere.
Widgets Layer
Complex, composite UI blocks with their own logic, used across multiple pages.
widgets/
├── header/
│ ├── ui/
│ │ ├── Header.tsx
│ │ ├── Navigation.tsx
│ │ └── UserMenu.tsx
│ ├── model/
│ │ └── headerStore.ts ← Widget state
│ ├── api/
│ │ └── fetchNotifications.ts ← Widget-specific API
│ └── index.ts
├── sidebar/
│ ├── ui/
│ ├── model/
│ │ └── sidebarState.ts
│ └── index.ts
└── footer/
v2.1 Approach: Widgets are no longer just compositional blocks. They can contain:
- ✅ UI components of the widget
- ✅ Widget-specific state management
- ✅ Business logic that serves the widget
- ✅ API interactions the widget needs
- ✅ Internal utilities
Only extract code to entities/features when other widgets or pages need it.
Features Layer
Reusable user interactions and complete business features used in multiple places.
features/
├── auth/
│ ├── ui/
│ │ ├── LoginForm.tsx
│ │ └── RegisterForm.tsx
│ ├── model/
│ │ └── useAuth.ts
│ ├── api/
│ │ ├── login.ts
│ │ └── register.ts
│ └── index.ts
├── add-to-cart/
├── like-post/
└── comment-create/
v2.1 Approach: Only create a feature when:
- ✅ The user interaction is used on multiple pages/widgets
- ✅ It's a complete, self-contained user action
- ✅ It has clear business value
Don't create features prematurely. If a user interaction is only used in one place, keep it in the page or widget until you actually need to reuse it.
Entities Layer
Reusable business entities - the core domain models used across the application.
entities/
├── user/
│ ├── ui/
│ │ ├── UserCard.tsx
│ │ └── UserAvatar.tsx
│ ├── model/
│ │ ├── types.ts
│ │ └── userStore.ts
│ ├── api/
│ │ └── userApi.ts
│ ├── @x/
│ │ └── order.ts ← Cross-import API for order
│ └── index.ts
├── product/
└── order/
v2.1 Approach: Only create an entity when:
- ✅ It represents a clear business domain concept
- ✅ It's used in multiple features, pages, or widgets
- ✅ It has well-defined boundaries and responsibilities
Don't prematurely extract entities. If a data structure is only used in one place, keep it there until you need to share it.
Shared Layer
Reusable infrastructure code with no business logic.
shared/
├── ui/ ← UI kit components
│ ├── Button/
│ ├── Input/
│ └── Modal/
├── lib/ ← Utilities
│ ├── formatDate/
│ ├── debounce/
│ └── classnames/
├── api/ ← API client setup, base config
│ ├── client.ts
│ └── apiRoutes.ts ← Route constants (v2.1: allowed!)
├── config/ ← Environment variables, constants
│ ├── env.ts
│ └── appConfig.ts
├── assets/ ← Images, fonts, icons
│ ├── logo.svg ← Company logo (v2.1: allowed!)
│ └── icons/
└── types/ ← Common TypeScript types
v2.1 Update: Shared can now contain application-aware code:
- ✅ Route constants and path builders
- ✅ API endpoint definitions
- ✅ Company branding assets (logos, colors)
- ✅ Application configuration
- ✅ Common type definitions
Still not allowed:
- ❌ Business logic (calculations, workflows, domain rules)
- ❌ Feature-specific code
- ❌ Entity-specific code
No slices in Shared - organized by segments only. Segments can import from each other within Shared.
Common Patterns
1. Working with API (Pages First Approach)
Start simple - keep API logic in the page until you need to reuse it:
export const fetchProfile = (id: string) =>
apiClient.get(`/users/${id}`);
export const useProfile = (id: string) => {
const [user, setUser] = useState(null);
useEffect(() => {
fetchProfile(id).then(setUser);
}, [id]);
return user;
};
import { useProfile } from '../model/useProfile';
const
