Feature-Sliced Design

What Feature-Sliced Design is

Feature-Sliced Design (FSD) is an architecture methodology for the frontend, with strict rules about where you put code and who may import what. Code is split by how business-specific it is — from pages (very specific) down to utilities (generic).

Feature-Sliced Design in 1 minute

FSD organizes code on 3 levels: layers → slices → segments.

• src/
  • app/global setup: providers, styles, init
  • views/pages ("pages" in FSD; renamed so it doesn't clash with Next)
  • widgets/big composed UI blocks: header, sidebar, playground
  • features/user actions with business value: run-exercise, add-to-cart
  • entities/business concepts: user, lesson, product, progress
  • shared/generic code, no business: ui kit, lib, api client, config

The golden rule

A layer may import only from the layers below it.

views→widgets→features→entities→shared

• features/run-exercise can use entities/exercise ✓
• entities/exercise can NOT use features/... ✗
• Two slices in the same layer don't import each other (features/a ✗→ features/b). You combine them one level up (a widget/view).

Slices and segments

A slice = one concept (entities/lesson). Inside it, segments by technical role:

How we use it in this project

• app/[locale]/[topic]/[lesson]/page.tsxjust composes the view
• src/
  • views/lesson/ui/lesson-view.tsx
  • widgets/playground/ui/playground.tsx
  • features/run-exercise/lib/run-js.ts
  • entities/lesson/
    • api/lesson-api.ts
    • ui/lesson-content.tsx

Our convention: no index.ts that re-exports — we import directly from the file, with descriptive kebab-case names. Official FSD recommends an index.ts as each slice's public API; we drop it for easier searching, a faster dev server and zero accidental circular dependencies. The cost: the discipline of "don't import internal details" is on you, not on the structure.

FSD + the Next App Router

• The root app/ folder is Next's routing — thin files that import from views.
• FSD's pages layer → we call it views (to avoid confusion with the Pages Router).
• FSD's app layer (providers, global CSS) can live in app/layout.tsx or in src/app.

Pros / cons

Summary

• 6 layers, from specific to generic: app → views → widgets → features → entities → shared.
• Imports only go down; slices in the same layer don't import each other.
• Here: no barrels, descriptive kebab-case files, the root app/ only for routing.

Official sources

• Feature-Sliced Design — Overview
• FSD — Layers
• FSD — Usage with Next.js
• Steiger — linter FSD