Introduction
Every React developer starts the same way. You create a components folder, add a hooks folder, maybe a utils folder, and call it a day. It works great — until it doesn't.
Six months later, your components folder has 80 files. You have a UserCard next to a Sidebar next to a formatDate utility that somehow ended up as a component. Nobody on the team knows where to put new files. Every PR becomes a debate about folder structure.
This is not a skill issue. It's an architecture issue. And Feature-Sliced Design (FSD) solves it.
————————————————————————————————————
What is Feature-Sliced Design?
FSD is a frontend architecture methodology — not a library, not a framework. It's a set of rules for organizing your code that scales from small projects to enterprise applications.
It has three core concepts: Layers, Slices, and Segments.
————————————————————————————————————
Layers
Your entire codebase is divided into 6 layers, stacked from top to bottom:
<>app/ → Global config, providers, styles
pages/ → Route-level components
widgets/ → Large composite UI blocks
features/ → User interactions and actions
entities/ → Business objects
shared/ → Reusable utilities, UI kit, configs<>
The golden rule: a layer can only import from layers below it.features can import from entities and shared. But entities can never import from features. This one rule eliminates 90% of circular dependency problems.
————————————————————————————————————
Slices
Inside each layer, you split code by business domain. These are your slices:
<>entities/
user/
product/
order/
features/
auth/
search/
add-to-cart/<>
Each slice is isolated. It doesn't directly import from sibling slices. This means changing the user entity never accidentally breaks the product entity.
————————————————————————————————————
Segments
Inside each slice, you have segments — standardized folders with clear responsibilities:
<>entities/user/
ui/ → UserCard, UserAvatar components
model/ → Zustand store, types, hooks
api/ → API calls
lib/ → Helper functions
index.ts → Public API — only export what others need<>
The index.ts public API is crucial. Other slices import only from this file, not from deep inside the slice. This keeps your internal implementation private and refactorable.
————————————————————————————————————
Before and After
Let's say you're building a job marketplace. Here's what it looks like:
<>❌ Before FSD:
src/
components/
JobCard.tsx
JobList.tsx
UserProfile.tsx
CompanyCard.tsx
Header.tsx
Sidebar.tsx
FilterPanel.tsx
ApplyModal.tsx
hooks/
useJobs.ts
useUser.ts
useFilters.ts
utils/
formatSalary.ts
formatDate.ts
pages/
Jobs.tsx
Profile.tsx<>
After 6 months this components folder becomes a graveyard. Nobody knows if JobCard is a shared component or specific to one page. useJobs — is it a feature or an entity?
<>✅ After FSD:
src/
pages/
jobs/
profile/
widgets/
header/
sidebar/
job-feed/
features/
apply-for-job/
filter-jobs/
auth/
entities/
job/
ui/ → JobCard
model/ → types, store
api/ → getJobs, getJobById
index.ts
user/
ui/ → UserAvatar
model/ → useUser, UserStore
api/ → getUser
index.ts
company/
shared/
ui/ → Button, Input, Modal
lib/ → formatDate, formatSalary
config/ → constants, env
api/ → base fetch wrapper<>
Every file has exactly one correct place to live. A new developer joining the team can navigate the codebase without a guide.
————————————————————————————————————
When NOT to use FSD
FSD is not for every project. Be honest with yourself:
- Small projects under 3 months — the overhead is not worth it. A simple structure works fine.
- Solo weekend projects — just ship it.
- Team of 1 — you can get away with less structure.
FSD shines when: the project will live for 1+ years, multiple developers work on it, or the business domain is complex with many interconnected parts.
————————————————————————————————————
Getting Started — Minimal Template
If you want to try FSD today, start with just 3 layers:
<>src/
pages/ → your routes
entities/ → your core business objects
shared/
ui/ → Button, Input, etc.
lib/ → utilities
config/ → constants<>
Add widgets and features only when you feel the need. Don't over-architect from day one.
<>// shared/ui/index.ts
export { Button } from './Button'
export { Input } from './Input'
// entities/user/index.ts
export { UserCard } from './ui/UserCard'
export type { User } from './model/types'
// pages/profile/index.tsx
import { UserCard } from '@/entities/user'
import { Button } from '@/shared/ui'<>
————————————————————————————————————
Conclusion
FSD won't make you a better programmer overnight. But it will make your codebase significantly easier to maintain, onboard new developers into, and scale over time.
The mental model is simple: every piece of code has exactly one correct place to live. Once you internalize that, you'll never go back to the components dump folder.
If you want to go deeper, the official documentation at feature-sliced.design is excellent.