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 entityKey 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:
// features/auth/index.ts
export { LoginForm } from './ui/LoginForm';
export { useAuth } from './model/useAuth';
export { loginUser } from './api/loginUser';
// Internal files not exported remain private to the sliceRule: 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.ts
export { UserCard } from './ui/UserCard';
export { userModel } from './model';
// entities/user/@x/order.ts
// Cross-import API specifically for the order entity
export { UserOrderHistory } from './ui/UserOrderHistory';
export { getUserOrders } from './api/getUserOrders';
// entities/order/index.ts
import { UserOrderHistory } from '@/entities/user/@x/order';
// Now order can import from user's cross-import APIWhen 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 configurationPages 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 typesv2.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:
// pages/profile/api/fetchProfile.ts
export const fetchProfile = (id: string) =>
apiClient.get(`/users/${id}`);
// pages/profile/model/useProfile.ts
export const useProfile = (id: string) => {
const [user, setUser] = useState(null);
useEffect(() => {
fetchProfile(id).then(setUser);
}, [id]);
return user;
};
// pages/profile/ui/ProfilePage.tsx
import { useProfile } from '../model/useProfile';
const ProfilePage = () => {
const user = useProfile('123');
return <div>{user?.name}</div>;
};Only move to entities when other pages need the same API:
// entities/user/api/userApi.ts
export const fetchUser = (id: string) =>
apiClient.get(`/users/${id}`);
// entities/user/model/userStore.ts
export const useUser = (id: string) => {
const [user, setUser] = useState(null);
useEffect(() => {
fetchUser(id).then(setUser);
}, [id]);
return user;
};
// entities/user/index.ts
export { useUser } from './model/userStore';
export type { User } from './model/types';
// Now multiple pages can use it:
// pages/profile/ui/ProfilePage.tsx
// pages/user-list/ui/UserListPage.tsx
import { useUser } from '@/entities/user';2. Feature Composition
Features can use entities and other features:
// features/post-card/ui/PostCard.tsx
import { UserAvatar } from '@/entities/user';
import { LikeButton } from '@/features/like-post';
import { CommentButton } from '@/features/comment-create';
export const PostCard = ({ post }) => (
<article>
<UserAvatar userId={post.authorId} />
<h2>{post.title}</h2>
<p>{post.content}</p>
<div>
<LikeButton postId={post.id} />
<CommentButton postId={post.id} />
</div>
</article>
);3. Handling Routes
Routes should be defined in the App layer, pages composed in Pages layer:
// app/router.tsx
import { HomePage } from '@/pages/home';
import { ProfilePage } from '@/pages/profile';
export const router = createBrowserRouter([
{ path: '/', element: <HomePage /> },
{ path: '/profile/:id', element: <ProfilePage /> },
]);
// app/index.tsx
import { RouterProvider } from 'react-router-dom';
import { router } from './router';
export const App = () => <RouterProvider router={router} />;4. Shared UI Components
// shared/ui/Button/Button.tsx
export const Button = ({ children, onClick, variant = 'primary' }) => (
<button className={`btn btn-${variant}`} onClick={onClick}>
{children}
</button>
);
// shared/ui/Button/index.ts
export { Button } from './Button';
export type { ButtonProps } from './Button';
// Usage in feature
import { Button } from '@/shared/ui/Button';
const LoginForm = () => (
<form>
<Button variant="primary">Login</Button>
</form>
);Path Aliases
Use path aliases for clean imports:
// tsconfig.json
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/app/*": ["src/app/*"],
"@/pages/*": ["src/pages/*"],
"@/widgets/*": ["src/widgets/*"],
"@/features/*": ["src/features/*"],
"@/entities/*": ["src/entities/*"],
"@/shared/*": ["src/shared/*"]
}
}
}Decision Framework (v2.1 "Pages First")
When creating new code, follow this decision tree:
- Start with: "Where is this code used?"
- Used in only one page? → Keep it in that page/ - Used in one widget across multiple pages? → Keep it in that widget/ - Used across multiple pages/widgets? → Continue to question 2
- Is it reusable infrastructure?
- UI component with no business logic? → shared/ui/ - Utility function (date formatting, etc.)? → shared/lib/ - API client setup, route constants? → shared/api/ or shared/config/ - If yes to any → shared/ - If no → Continue to question 3
- Is it a complete user action?
- User interaction (login, add to cart, like post)? → features/ - But only if it's reused in multiple places!
- Is it a business domain concept?
- Core business entity (user, product, order)? → entities/ - But only if it's reused in multiple places!
- Is it app-wide setup?
- Global provider, router, theme? → app/
Quick Decision Examples:
"User profile form with validation"
- Used only on profile page? →
pages/profile/ui/ProfileForm.tsx - Used on profile + settings pages? → Consider
features/profile-form/ - Still not sure? → Start in page, extract when you actually need it elsewhere
"Product card component"
- Shows on product list page only? →
pages/products/ui/ProductCard.tsx - Shows on multiple pages? →
widgets/product-card/orentities/product/ui/ProductCard.tsx - Generic card layout? →
shared/ui/Card/
"Fetch product data"
- Only product detail page needs it? →
pages/product-detail/api/fetchProduct.ts - Multiple pages need it? →
entities/product/api/productApi.ts
"Modal manager"
- Infrastructure for showing modals? →
shared/ui/modal-manager/ - Content of specific modals? → Keep in pages that use them
The Golden Rule:
"When in doubt, keep it in pages/widgets. Extract to lower layers when you actually need to reuse it."
Don't try to predict reusability. Wait for actual reuse to emerge, then refactor.
Anti-Patterns to Avoid
❌ Premature extraction (v2.1 key anti-pattern)
// Immediately creating an entity/feature before knowing if it's needed
// entities/user-profile-form/ ← Used only on one page!✅ Solution: Keep in page until actually needed elsewhere
// pages/profile/ui/ProfileForm.tsx ← Start here
// Only move to features/ when another page needs it❌ Cross-imports between slices on same layer
// features/comments/ui/CommentList.tsx
import { likePost } from '@/features/like-post'; // BAD!✅ Solution: Use @x notation for entities, or compose at higher layer
// For entities with business relationships:
// entities/user/@x/order.ts
export { UserOrderHistory } from './ui/UserOrderHistory';
// For features, compose at page level:
// pages/post/ui/PostPage.tsx
import { CommentList } from '@/features/comments';
import { LikeButton } from '@/features/like-post';❌ Business logic in Shared
// shared/lib/userHelpers.ts
export const calculateUserReputation = (user) => { ... }; // BAD!✅ Solution: Move to entities layer
// entities/user/lib/calculateReputation.ts
export const calculateUserReputation = (user) => { ... };❌ Bypassing public API
import { LoginButton } from '@/features/auth/ui/LoginButton'; // BAD!✅ Use public API
import { LoginButton } from '@/features/auth'; // GOOD!❌ God slices (too much responsibility)
// features/user-management/ ← TOO BROAD
// - login, register, profile-edit, password-reset, etc.✅ Split into focused features
// features/auth/
// features/profile-edit/
// features/password-reset/Migration from FSD v2.0 to v2.1
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 compositionAfter (v2.1):
pages/
└── profile/
├── ui/
│ ├── ProfilePage.tsx
│ └── ProfileForm.tsx ← Moved here
├── model/
│ └── profileStore.ts ← Moved here
└── api/
└── updateProfile.ts ← Moved hereMigration 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.
Working with Different Technologies
React + Redux
features/
└── todo-list/
├── ui/
│ └── TodoList.tsx
├── model/
│ ├── todoSlice.ts ← Redux slice
│ ├── selectors.ts ← Selectors
│ └── thunks.ts ← Async actions
└── index.tsReact + React Query
entities/
└── user/
├── ui/
├── api/
│ └── userQueries.ts ← React Query hooks
├── model/
│ └── types.ts
└── index.tsNext.js
Place FSD structure in src/ folder to avoid conflicts with Next.js app/ or pages/ folders:
my-nextjs-project/
├── app/ ← Next.js App Router (if using)
├── pages/ ← Next.js Pages Router (if using)
└── src/
├── app/ ← FSD app layer
├── pages/ ← FSD pages layer
├── widgets/
├── features/
├── entities/
└── shared/Framework Integration Examples
Vite + React + TypeScript
project/
├── src/
│ ├── app/
│ ├── pages/
│ ├── widgets/
│ ├── features/
│ ├── entities/
│ └── shared/
├── tsconfig.json
├── vite.config.ts
└── package.jsonCreate React App
project/
└── src/
├── app/
├── pages/
├── widgets/
├── features/
├── entities/
└── shared/Key Reminders (v2.1)
- Pages First: Start by keeping code in pages/widgets, extract only when you need to reuse
- Wait for actual reuse: Don't predict reusability, let it emerge naturally
- Think in layers: Determine responsibility level before creating files
- Slices are independent: No imports between slices on the same layer (except @x for entities)
- High cohesion: Keep related code together in slices
- Public API is mandatory: Always define what's exported via index.ts
- Business logic can live in pages/widgets: Don't extract prematurely
- Shared is for infrastructure: Now can include app-aware code (routes, assets) but no business logic
- Processes layer deprecated: Move code to features/ with app/ layer help
- Use @x for entity relationships: Make cross-dependencies explicit and controlled
- Segments can import each other: In App and Shared layers
- Follow the import rule: Only import from layers below
Quick Reference
Layer Selection:
- Global setup →
app/ - Routes →
pages/ - Reusable composites →
widgets/ - User actions →
features/ - Business models →
entities/ - Infrastructure →
shared/
Import Direction: App → Pages → Widgets → Features → Entities → Shared
Public API: Always create index.ts for slices to export public interface
Additional Resources
For more detailed information and edge cases:
- Cross-imports: When slices need to communicate
- Desegmentation: Why grouping by tech role is anti-pattern
- Routing: Advanced routing patterns
- SSR: Server-side rendering implementation
- Monorepos: Multi-package FSD setup
Implementation Checklist
When implementing FSD in a project:
- Setup path aliases in tsconfig.json
- Create layer folders: app/, pages/, widgets/, features/, entities/, shared/
- Move UI kit to shared/ui/
- Move utilities to shared/lib/
- Start with pages/ - keep code there first
- 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/steigerUsage:
npx steiger srcSteiger 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:
- ✅ Better code cohesion (related code stays together)
- ✅ Easier refactoring (everything is in one place)
- ✅ Faster development (no premature abstractions)
- ✅ Clearer architecture (only necessary abstractions exist)
- ✅ Less cognitive overhead (simpler mental model)
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.