\n\nSource: fsd.how | Strictness can be adjusted based on\nproject scale and team context.
\n
How to use this skill. For placement decisions, start with the decision\ntree in Section 2 and use the placement table in Section 3 as a quick\nreference. To check a structure for violations, use the rules in Section 4.\nTo resolve same-layer cross-imports, use Section 7. For task-specific\nguidance, load only the relevant reference files from Section 10; do not\npreload the rest.
\nFSD v2.1 core principle: \"Start simple, extract when needed.\"
\nPlace code in pages/ first. Duplication across pages is acceptable and\ndoes not by itself require extraction to a lower layer. Extract only when\nall three conditions hold:
Not all layers are required. Most projects can start with only shared/,\npages/, and app/. Add features/ and entities/ only when they provide\nclear value. Do not create empty layer folders \"just in case.\" The widgets/\nlayer is discouraged (see the callout below).
FSD uses 6 standardized layers, listed here from highest to lowest:
\napp/ → App initialization, providers, routing\npages/ → Route-level composition, owns its own logic\nwidgets/ → Reusable UI blocks (discouraged, see the callout below)\nfeatures/ → Reusable user interactions (see the extraction rule above)\nentities/ → Reusable business domain models (see the extraction rule above)\nshared/ → Infrastructure with no business logic (UI kit, utils, API client)\nThe official layer reference discourages using the Widgets layer, and\nthis skill follows it. Widgets may seem useful for representing independent\nUI blocks. However, in real frontend code, UI blocks often include logic\nrequired for user flows, such as data fetching, state management, and event\nhandling. In this case, the responsibilities of Features, which handle user\nflows, and Widgets, which handle UI blocks, can overlap, making the boundary\nbetween the two layers unclear.
\nNot creating a widget does not mean moving the block elsewhere untouched.\nA screen-specific composition stays in pages; a reused action and the UI\nto perform it go to features; context-free UI goes to shared; an\napp-wide layout goes to app.
Discouraged is not deprecated: an existing widgets layer stays valid. See\nreferences/layer-structure.md for that case and for layout placement.
A module may only import from layers strictly below it. Cross-imports\nbetween slices on the same layer are forbidden, with one narrow exception\nin Section 7.
\n// Allowed\nimport { Button } from \"@/shared/ui/Button\"; // features → shared\nimport { useUser } from \"@/entities/user\"; // pages → entities\n\n// Violation\nimport { loginUser } from \"@/features/auth\"; // entities → features\nimport { likePost } from \"@/features/like-post\"; // features → features\nNote: The processes/ layer is deprecated in v2.1. For migration\ndetails, read references/migration-guide.md.
When writing new code, follow this tree:
\nStep 1: Where is this code used?
\npages/ slice.insignificant-slice).Step 2: Is it reusable infrastructure with no business logic?
\nThe official layer reference draws the line for Shared like this: no\nbusiness logic, but business-themed is fine (a company logo, a page\nlayout), and so is UI logic (autocomplete, a search bar). Exchanging data\nwith the backend and CRUD boilerplate are not business logic either.\nBusiness logic is a rule the product enforces on its own data, such as\napplying a discount to an order. If the code fits none of the exclusions\nand still does not clearly enforce a product rule, the term does not\ndecide; go back to Step 1 and place it by where it is used.
\nshared/ui/shared/lib/shared/api/ or shared/config/shared/auth/shared/api/ (a single caller keeps\nit, see Step 1)Step 3: Is it a complete user action that several consumers share, with\na focused responsibility and a reason to change of its own?
\nfeatures/Step 4: Is it a business domain model that several consumers share, with\na focused responsibility and a reason to change of its own?
\nentities/Step 5: Is it app-wide configuration?
\napp/Golden Rule: When in doubt, keep it in pages/. Extract only when the\nextraction rule holds.
| Scenario | \nSingle use | \nConfirmed multi-use | \n
|---|---|---|
| User profile form | \npages/profile/ui/ProfileForm.tsx | \nfeatures/profile-form/ | \n
| Product card | \npages/products/ui/ProductCard.tsx | \nentities/product/ui/ if the entity owns it | \n
| API request (read or CRUD) | \npages/product-detail/api/fetch-product.ts | \nshared/api/ (no domain rules) | \n
| Auth token/session | \nshared/auth/ | \nshared/auth/ | \n
| Auth login form | \npages/login/ui/LoginForm.tsx | \nfeatures/auth/ | \n
| Generic Card layout | \n\n | shared/ui/Card/ | \n
| Modal manager | \n\n | shared/ui/modal-manager/ | \n
| Modal content | \npages/[page]/ui/SomeModal.tsx | \n\n |
| Date formatting util | \n\n | shared/lib/format-date.ts | \n
\"Confirmed multi-use\" means the extraction rule holds, not that a second\nconsumer appeared: two similar copies that keep drifting apart stay in\ntheir pages (references/growth-walkthrough.md, Snapshot 1). Entity UI\ncarries the Section 6 caution even when the rule does hold.
These rules are the foundation of FSD. Violations weaken the architecture.\nIf you must break a rule, ensure it is an intentional design decision and\ndocument the reason in code (a comment or ADR).
\napp → pages → widgets → features → entities → shared.\nUpward imports are forbidden. So are cross-imports between slices on the\nsame layer, except through the other slice's public API as a last resort\n(Section 7, Strategy D).
External consumers may only import from a slice's index.ts. Direct imports\nof internal files are forbidden.
// Correct\nimport { LoginForm } from \"@/features/auth\";\n\n// Violation: bypasses public API\nimport { LoginForm } from \"@/features/auth/ui/LoginForm\";\nShared layer: Shared has no slices. Define a separate public API per\nsegment (shared/ui/index.ts, shared/api/index.ts, etc.) rather than\none top-level shared/index.ts. This keeps imports from Shared\norganized by intent.
Where one index over a segment's unrelated modules hurts bundling, give\neach component, library, or controller folder its own index instead\n(shared/ui/Button/index.ts as @/shared/ui/Button, shared/api/post/\nas @/shared/api/post). That folder is then the boundary; reaching past\nit (@/shared/ui/Button/Button.tsx) is still a violation. See\nreferences/layer-structure.md for the shape.
Environment-specific entry points: a slice normally exposes one\nindex.ts, and ad-hoc variations are not recommended. If a single index\ncannot preserve a runtime boundary, add an entry point such as\nindex.server.ts. See references/framework-integration.md.
If two slices on the same layer need to share logic, follow the resolution\norder in Section 7. Never reach into another slice's internals.
\nName files after what they are for, the domain or concern they serve, not\nafter their technical role. Technical-role names like types.ts,\nutils.ts, helpers.ts mix unrelated concerns in a single file and\nreduce cohesion.
// BAD: technical-role naming\nmodel/types.ts ← Which types? User? Order? Mixed?\nmodel/utils.ts\n\n// GOOD: domain-based naming\nmodel/user.ts ← User types + related logic\nmodel/order.ts ← Order types + related logic\napi/fetch-profile.ts ← Clear purpose\nShared contains only infrastructure: UI kit, utilities, API client setup,\nroute constants, assets. Business calculations, domain rules, and workflows\nbelong in entities/ or higher layers. Section 2, Step 2 says what counts.
// BAD: business logic in shared\n// shared/lib/userHelpers.ts\nexport const calculateUserReputation = (user) => { ... };\n\n// GOOD: move it to whoever owns the rule\n// pages/profile/model/reputation.ts ← while the profile page owns it\n// entities/user/model/reputation.ts ← once a user boundary is earned\nexport const calculateUserReputation = (user) => { ... };\nPlace code in pages/ first. Extract to lower layers only when truly needed.\nExtraction is a design decision that affects the whole project, so the\nthreshold should be high.
What stays in pages:
\nEvolution pattern: Start with everything in pages/profile/. Extract\nthe shared model to entities/user/ when a second page consumes it and\nthe extraction rule holds. A response type that several pages read is not\none of those cases: it stays in shared/api. Keep page-specific API calls\nand UI in the page.
The entities layer is highly accessible (almost every other layer can import\nfrom it), so changes propagate widely.
\nshared/ + pages/ + app/ is valid FSD.\nThin-client apps rarely need entities.shared/api and logic in the current slice's model/ segment may\nbe sufficient.shared/api/\nonce several slices call it.shared/auth/ or shared/api/. Tokens and login\nDTOs are auth-context-dependent and rarely reused outside authentication.For detailed guidance on keeping the entities layer clean (when to skip\nit entirely, how to isolate business contexts, why CRUD belongs in\nshared/api), see references/excessive-entities.md.
// Valid minimal FSD project\nsrc/\n app/ ← Providers, routing\n pages/ ← All page-level code\n shared/ ← UI kit, utils, API client\n\n// Add layers only when an actual use case requires them:\n// + features/ ← User-action boundaries that need one shared home\n// + entities/ ← Domain boundaries that need one shared home\n// (widgets/ is discouraged; see Section 1 for where that code goes instead)\nSteiger is the official FSD\nlinter. Key rules:
\ninsignificant-slice: Flags a slice with no references, or with one,\nand suggests merging it into the layer above. Pages may hold a single\nreference, and so may slices used only from app/.excessive-slicing: Suggests merging or grouping when a layer has too\nmany slices.npm install -D @feature-sliced/steiger\nnpx steiger src\nshared/api/. An\noperation that carries business rules is placed by who owns the rule,\nwhich may be an entity, a feature, or the page running the workflow.user entity just for auth data. Tokens and login DTOs\nbelong in shared/auth/ or shared/api/.@x. It is a necessary compromise, not a recommended\npattern. The notation is for the entities layer only, and only when\nboundary merge is genuinely impossible. Features and widgets handle\ncross-imports through strategies A through D (see Section 7).user-management/ into\nauth/, profile-edit/, password-reset/).assets/ segment. Place static assets next\nto the code that uses them; global stylesheets and fonts go to app/.\nSee references/asset-handling.md.Cross-imports are a code smell, not an absolute prohibition. The right\nstrategy depends on the layer and the situation.
\nCross-imports in entities are usually caused by splitting entities too\ngranularly. Before reaching for @x, consider whether the boundaries\nshould be merged.
@x is a necessary compromise, not a recommended approach. Use it only\nwhen boundaries genuinely cannot be merged, and document why. Overuse locks\nentity boundaries together and increases refactoring cost.
In features and widgets, choose based on context:
index.ts. Never reach into model/,\nstore/, or internal files.The @x notation is for the entities layer only. Features and widgets use\nstrategies A through D above.
Cross-imports are dependencies that are generally best avoided, but\nsometimes used intentionally. Strictness varies by project context:
\nIf a cross-import is introduced, treat it as a deliberate choice and\ndocument the reasoning in code (a comment explaining why other strategies\ndo not apply).
\nFor detailed code examples of each strategy, read\nreferences/cross-import-patterns.md.
Segments group code within a slice by technical purpose:
\nui/: UI components, styles, display-related codemodel/: Data models, state stores, business logic, validationapi/: Backend integration, request functions, API-specific typeslib/: Internal utility functions for this sliceconfig/: Configuration, feature flagsreferences/layer-structure.md for details.Always use domain-based names that describe what the code is about:
\nmodel/user.ts ← User types + logic + store\nmodel/order.ts ← Order types + logic + store\napi/fetch-profile.ts ← Profile fetching\napi/update-settings.ts ← Settings update\nIf a segment has only one domain concern, the filename may match the slice\nname (e.g., features/auth/model/auth.ts).
Shared contains infrastructure with no business logic. It is organized by\nsegments only (no slices). Segments within shared may import from each other.
\nAllowed in shared:
\nui/: UI kit (Button, Input, Modal, Card)lib/: Utilities (formatDate, debounce, classnames)api/: API client, route constants, CRUD helpers, base typesauth/: Auth tokens, login utilities, session managementconfig/: Environment variables, app settingsassets/ segment.\nSee references/asset-handling.md.Shared may contain application-aware code: route constants, API\nendpoints, branding assets, and transport types such as ProductDTO.\nIt must never hold the business rules an entity or feature owns, nor\nimport from those layers.
Read the following reference files only when the specific situation applies.\nDo not preload all references.
\nWhen reviewing or reorganizing folder and file structure that already\nexists, deciding what goes inside a layer or slice, deciding where a page\nlayout belongs, routing widget-like code to another layer, or grouping\nclosely related slices into a parent folder for navigation (e.g., \"where\ndoes this folder go\", \"how do I group these payment entities\"):\n→ Read references/layer-structure.md
When setting up a new project from scratch (e.g., \"set up an FSD\nproject\", \"start a new app with FSD\"), or when asked whether to add\nentities or features yet, or to show how a structure earns each layer\nover time rather than its finished shape:\n→ Read references/growth-walkthrough.md
When resolving cross-import issues between slices on the same layer,\nevaluating the @x pattern, choosing between Strategy A/B/C/D for\nfeatures and widgets, or deciding whether boundaries should be merged:\n→ Read references/cross-import-patterns.md
When deciding whether to create or remove an entity, dealing with too\nmany entities, evaluating whether to skip the entities layer entirely,\nplacing CRUD operations, or isolating business contexts to avoid @x\nchains:\n→ Read references/excessive-entities.md
When deciding where to place static assets (images, icons, fonts,\nPDFs, stylesheets) for a single slice, for sharing across slices, or\nglobally:\n→ Read references/asset-handling.md
When migrating from FSD v2.0 to v2.1, converting a non-FSD codebase to\nFSD, phasing out an existing widgets layer, or deprecating the processes\nlayer:\n→ Read references/migration-guide.md
When integrating FSD with a specific framework (Next.js with App Router\nor Pages Router, React Router, Nuxt, Vite, Astro) for wiring routes to\nFSD pages, placing proxy/middleware and instrumentation files,\nstructuring API\nroute handlers, or configuring path aliases:\n→ Read references/framework-integration.md
When implementing authentication, type definitions, or API request\nhandling as concrete code within FSD structure (token storage, login\nflow, DTO placement, where a request function lives):\n→ Read references/auth-and-api.md
When wiring state management (Redux slices, TanStack Query / React\nQuery, including query factories, infinite scroll, Suspense mode, and\nuseMutationState) into FSD structure:\n→ Read references/state-management.md