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"?

1. Better code cohesion - related code stays together
2. Easier to delete - unused code is right there with its usage
3. Less abstraction overhead - no need to identify entities/features prematurely
4. Natural decomposition - pages are intuitive to understand
5. 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 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.ts
export { 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.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 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.

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:

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