Feature-Sliced Design

What this skill does

# Feature-Sliced Design

## Purpose

Feature-Sliced Design (FSD) is an architectural methodology for organizing frontend applications into a standardized, scalable structure. It provides clear separation of concerns through a layered hierarchy that prevents circular dependencies and promotes maintainability.

**Why use FSD:**
- **Scalability**: Grows naturally as your application expands
- **Maintainability**: Clear boundaries make refactoring safer
- **Team collaboration**: Consistent structure enables parallel development
- **Onboarding**: New developers understand architecture quickly

**Custom 'views' layer:**
This skill uses 'views' instead of the standard FSD 'pages' layer to avoid confusion with Next.js App Router's `/app` directory. The `/app` directory handles routing only (minimal logic), while `/src/views` contains your actual page business logic.

**Next.js integration:**
FSD works seamlessly with Next.js App Router by separating routing concerns (in `/app`) from business logic (in `/src/views` and other FSD layers). This keeps your routing configuration clean while maintaining FSD's architectural benefits.

## When to Use

Apply Feature-Sliced Design when:
- Starting new Next.js projects that require clear architectural boundaries
- Refactoring growing codebases that lack consistent structure
- Working with multi-developer teams needing standardized organization
- Building applications with complex business logic requiring separation of concerns
- Developing Turborepo monorepo applications where each app needs independent FSD structure
- Scaling applications where circular dependencies become problematic
- Creating enterprise applications with long-term maintenance requirements

## Core Principles

### Layer Hierarchy

FSD organizes code into **7 standardized layers** (from highest to lowest):

1. **app** - Application initialization, global providers, routing configuration
2. **processes** - Deprecated (functionality moved to features and app)
3. **views** - Page-level business logic (custom naming, replaces standard 'pages')
4. **widgets** - Large composite UI blocks that span multiple features
5. **features** - User-facing interactions with business value
6. **entities** - Business domain objects and models
7. **shared** - Reusable utilities, UI kit, third-party integrations

**Import rule:** A module can only import from layers **strictly below** it in the hierarchy.

```
┌─────────────────┐
│      app        │  ← Can import from all layers below
├─────────────────┤
│     views       │  ← Can import: widgets, features, entities, shared
├─────────────────┤
│    widgets      │  ← Can import: features, entities, shared
├─────────────────┤
│    features     │  ← Can import: entities, shared
├─────────────────┤
│    entities     │  ← Can import: shared only
├─────────────────┤
│     shared      │  ← Cannot import from any FSD layer
└─────────────────┘
```

This hierarchy prevents circular dependencies and ensures clear architectural boundaries.

### 'Views' vs 'Pages' Layer

**Why 'views' instead of 'pages':**
- Next.js uses `/app` directory for routing (App Router)
- Standard FSD uses 'pages' layer for page business logic
- Using 'views' eliminates confusion between routing (`/app`) and business logic (`/src/views`)

**Separation of concerns:**
- **`/app` directory (root level)**: Next.js routing only, minimal logic
  - Contains `page.tsx`, `layout.tsx`, route groups
  - Imports and renders from `/src/views`
- **`/src/views` layer (FSD)**: Page business logic, component composition
  - Contains view components, models, API calls
  - Composes widgets, features, entities

This separation keeps routing configuration clean while maintaining FSD architectural principles.

### Slices

**Slices** are domain-based partitions within layers (except app and shared, which have no slices).

**Examples:**
- `views/dashboard` - Dashboard page slice
- `widgets/header` - Header widget slice
- `features/auth` - Authentication feature slice
- `entities/user` - User entity slice

**Public API pattern:**
Each slice exports through `index.ts` to control its public interface:

```typescript
// src/features/auth/index.ts
export { LoginForm } from './ui/LoginForm';
export { useAuth } from './model/useAuth';
export type { AuthState } from './model/types';
// Internal implementation details NOT exported
```

This prevents deep imports and maintains encapsulation.

### Segments

**Segments** are purpose-based groupings within slices:

- **ui/** - React components, visual elements
- **model/** - Business logic, state management, TypeScript types
- **api/** - API clients, data fetching, external integrations
- **lib/** - Utility functions, helpers specific to the slice
- **config/** - Configuration constants, feature flags

**Example structure:**
```
features/
└── auth/
    ├── ui/
    │   ├── LoginForm.tsx
    │   └── SignupForm.tsx
    ├── model/
    │   ├── useAuth.ts
    │   └── types.ts
    ├── api/
    │   └── authApi.ts
    └── index.ts
```

## FSD with Next.js App Router

### Routing Architecture

Next.js App Router uses `/app` directory for routing. FSD layers live in `/src` directory.

**File organization:**
```
my-nextjs-app/
├── app/                          # Next.js routing (minimal logic)
│   ├── layout.tsx               # Root layout
│   ├── page.tsx                 # Home route
│   ├── dashboard/
│   │   └── page.tsx            # Dashboard route
│   └── settings/
│       └── page.tsx            # Settings route
│
├── src/                         # FSD layers
│   └── views/                  # Page business logic
│       ├── home/
│       │   ├── ui/
│       │   │   └── HomeView.tsx
│       │   └── index.ts
│       ├── dashboard/
│       │   ├── ui/
│       │   │   └── DashboardView.tsx
│       │   ├── model/
│       │   │   └── useDashboard.ts
│       │   └── index.ts
│       └── settings/
│           ├── ui/
│           │   └── SettingsView.tsx
│           └── index.ts
```

**Routing pages import from views:**
```typescript
// app/dashboard/page.tsx - Routing only
import { DashboardView } from '@/views/dashboard';

export default function DashboardPage() {
  return <DashboardView />;
}

// src/views/dashboard/ui/DashboardView.tsx - Business logic
import { Header } from '@/widgets/header';
import { StatsCard } from '@/features/analytics';

export function DashboardView() {
  return (
    <div>
      <Header />
      <StatsCard />
    </div>
  );
}
```

### Standalone Next.js Structure

Complete FSD structure for a standalone Next.js application:

```
my-nextjs-app/
├── app/                          # Next.js App Router
│   ├── layout.tsx               # Root layout
│   ├── page.tsx                 # Home route
│   ├── (auth)/                  # Route group
│   │   ├── login/
│   │   │   └── page.tsx
│   │   └── signup/
│   │       └── page.tsx
│   ├── dashboard/
│   │   └── page.tsx
│   ├── api/                     # API routes
│   │   └── users/
│   │       └── route.ts
│   └── not-found.tsx
│
├── src/
│   ├── app/                     # App layer (no slices)
│   │   ├── providers/
│   │   │   ├── AuthProvider.tsx
│   │   │   └── QueryProvider.tsx
│   │   ├── styles/
│   │   │   └── globals.css
│   │   └── config/
│   │       └── constants.ts
│   │
│   ├── views/                   # Views layer (page logic)
│   │   ├── home/
│   │   ├── dashboard/
│   │   ├── login/
│   │   └── signup/
│   │
│   ├── widgets/                 # Widgets layer
│   │   ├── header/
│   │   ├── sidebar/
│   │   ├── footer/
│   │   └── notification-panel/
│   │
│   ├── features/                # Features layer
│   │   ├── auth/
│   │   ├── search/
│   │   ├── theme-toggle/
│   │   └── user-profile/
│   │
│   ├── entities/                # Entities layer
│   │   ├── user/
│   │   ├── post/
│   │   ├── comment/
│   │   └── session/
│   │
│   └── shared/                  # Shared layer (no slices)
│       ├── ui/                  # UI components
│       │   ├── button/
│