React Feature-Sliced Design

Architectural guide for organizing React/TypeScript frontends following Feature-Sliced Design (FSD) — a methodology that splits code into layers and slices with strict dependency rules. Tailored for React function components, hooks, and the React ecosystem.

Why FSD

Every slice exposes a public API (index.ts) and hides its internals (ui/, model/, api/, lib/), so refactoring a slice cannot break its consumers. The layer and same-layer rules below keep those blast radiuses small: a change lands in one slice instead of cascading sideways.

Structure

src/
├── app/                # Providers, router, global styles, entry point (no slices)
├── pages/              # Route components (one per route)
├── widgets/            # Composite UI blocks
├── features/           # User interactions (auth, search, filters)
├── entities/           # Business domain (components, hooks, types)
└── shared/             # Reusable infrastructure (no slices)

app/ and shared/ are divided directly into segments — they do not contain slices.

Layer Dependencies

Imports flow down only: a slice may import from layers strictly below it, never from another slice on its own layer.

Layer Decision Guide

Slice Structure

Every slice follows the same internal layout (all segments optional):

{slice-name}/
├── ui/                 # Components (.tsx, one per file)
├── model/              # Hooks, state, types
├── api/                # Data fetching (REST/GraphQL)
├── lib/                # Pure helpers, utility hooks
├── config.ts           # Constants, configuration
├── index.ts            # PUBLIC API — only exports for external use
└── CLAUDE.md           # Purpose + non-obvious context (required)

Each segment directory has its own index.ts re-exporting all items. External code imports ONLY from the slice's root index.ts.

Naming Conventions

UI Library Integration

If using a component library:

• Base components live outside FSD layers (components/ui/ or node_modules)
• Never modify library components directly — wrap in shared/ui/ or slice ui/
• Domain-specific wrappers belong in the slice that uses them

CLAUDE.md in Every Slice

Every slice must have a CLAUDE.md. Keep it very short: what this module is for + anything non-obvious. Everything else is discoverable from code. See references/claude-md-template.md for the template.

Workflow: Adding a New Slice

1. Decide the layer — use the Layer Decision Guide above
2. Scaffold — create src/{layer}/{slice-name}/ with needed segments (ui/, model/, api/, lib/)
3. Write the public API — create index.ts with explicit named exports (no export *)
4. Validate imports — verify all imports flow downward only; no same-layer imports exist
5. Add CLAUDE.md — 1-3 sentences on what this slice does + any non-obvious context
6. Verify — check: (a) no upward imports, (b) external code only imports from index.ts, (c) no export * re-exports

Inline Example: Entity Slice

A minimal entities/customer/ slice:

// entities/customer/model/types.ts
export interface Customer {
  id: string;
  name: string;
  email: string;
  status: 'active' | 'inactive';
}

// entities/customer/model/use-customer.ts
import { useState, useEffect } from 'react';
import { fetchCustomer } from '../api';
import type { Customer } from './types';

export function useCustomer(id: string) {
  const [customer, setCustomer] = useState<Customer | null>(null);
  useEffect(() => { fetchCustomer(id).then(setCustomer); }, [id]);
  return customer;
}

// entities/customer/api/customer-api.ts
import type { Customer } from '../model';
export async function fetchCustomer(id: string): Promise<Customer> {
  const res = await fetch(`/api/customers/${id}`);
  return res.json();
}

// entities/customer/index.ts — PUBLIC API
export { useCustomer } from './model';
export type { Customer } from './model';
export { CustomerCard } from './ui';

Teaching Behavior

Actively teach FSD principles — explain decisions, don't just apply rules:

Common Violations Quick-Reference

Code Generation Rules

1. Co-locate logic in the owning slice — don't scatter across layers
2. Don't create shared code unless reused in 2+ places
3. Follow existing naming conventions in the project
4. Never pollute shared/ with domain-specific code
5. Always create proper index.ts public API
6. No wildcard re-exports — always list exports explicitly (export * from is forbidden)
7. When generating code, include a short comment or message explaining the FSD reasoning behind placement decisions

Deep Dives

Official FSD Specification

This skill is a React/TypeScript adaptation of Feature-Sliced Design. For the canonical spec, use WebFetch to read from fsd.how/llms.txt:

• Abridged: fsd.how/llms-small.txt — compact reference
• Complete: fsd.how/llms-full.txt — full documentation

These files are large, so fetching them by reflex wastes the engineer's context for no gain. Use WebFetch only when the engineer explicitly asks for the full FSD specification, or when you hit a question this skill doesn't answer.

Consult the official spec when you need details beyond what this skill covers (e.g., migration strategies, advanced decomposition patterns, framework-agnostic rules).