Feature-Sliced Design: the documentation repository behind the FSD methodology

What Feature-Sliced Design actually solves

The README frames the problem plainly: the methodology exists to make a project "more understandable and structured in the face of ever-changing business requirements." That is a maintainability problem, not a runtime one. Nothing in FSD makes an application faster or smaller. What it changes is where a new developer looks when they need to find the code behind a screen, and how much of the codebase they have to hold in their head before they can change it safely.

The intended audience is frontend teams whose code has outgrown a flat components folder plus a utils dumping ground. The README lists four benefits: uniformity (code organized by scope of influence, domain and technical purpose), controlled reuse of logic, stability under refactoring, and orientation to business needs. Each of those is a claim about human coordination, and each depends on the team actually following the conventions rather than merely reading them.

It is worth being blunt about what this repository is. feature-sliced/documentation is the documentation site. It is not a linter, not a scaffolding CLI, and not a runtime library. The README states that the methodology is not tied to a particular stack and can be used for web or native applications. That portability is a strength, but it also means the repository gives you rules and vocabulary, not enforcement.

Layers, slices and segments: how the structure is built

The README describes three axes of organization. Code is grouped by scope of influence into layers, by domain into slices, and by technical purpose into segments. A layer is a horizontal band with a defined rank. A slice is a vertical cut inside a layer, usually named after a business domain. A segment is the technical split inside a slice, such as UI, model or API.

The rule that does the real work is the dependency direction. According to the README, a module on a particular layer cannot use other modules on the same layer, or the layers above. Imports flow downward only. That single constraint is what the README means by "isolated modifications without unforeseen consequences": if you change something low in the stack, you know which direction the blast radius travels.

The slice axis is where the business orientation comes from. The README says that when the app is split into business domains, you can navigate the code to discover and understand the project features. This is the part that ages well. Layers are a technical decision made once; slices follow the product and change as the product does.

The v2.1 release, dated 2024-11-13, is titled "Pages come first!", which signals that page-level organization is the starting point in the current version. The repository does not spell out the full layer list in the README, so anyone implementing this should read the current pages at fsd.how rather than reconstructing the layers from the README alone.

Running the documentation site locally with pnpm

There is nothing to install into your application. The only installable thing here is the docs site itself, which is built with Astro and Starlight. The package.json declares "node": ">= 22" under engines and pins the package manager to [email protected], so the toolchain requirements are explicit. The repository is private in package.json ("private": true), which confirms it is not published for consumption.

Start by installing dependencies with pnpm, then run the dev server:

pnpm install
pnpm dev

The dev script maps to astro dev, so you should see Astro's local server URL printed in the terminal. The start script is an alias for the same command.

A production build goes through the same Astro pipeline:

pnpm build
pnpm preview

There is also a link-checking variant that sets an environment variable before building:

pnpm linkcheck

That runs the build with CHECK_LINKS=true, which is the closest thing in this repository to a correctness gate for the documentation itself. The test script chains lint and build together, and test:lint runs eslint over .ts, .tsx, .js, .jsx and .astro files plus a prettier check. If you are contributing prose rather than code, the format script applies prettier across the tree.

The methodology ships no enforcement, and that is the main risk

The most important limitation is structural: this repository contains documentation, and documentation cannot fail a build. The README says a module cannot use modules on the same layer or above, but nothing in the repository enforces that sentence. If your team violates the rule, the docs site will not notice and neither will your CI, unless you separately configure something like an import-boundary rule in your own linter.

That gap matters most during adoption. Existing codebases rarely map cleanly onto layers and slices, and the migration is a manual reclassification exercise. The README offers the badge and the GitHub topic feature-sliced to advertise that a project follows the methodology, but a badge is a claim, not a check.

The second limitation is fit. FSD is the wrong tool for small applications where the whole codebase fits in one person's head, and for prototypes where the product shape is still unknown. Slicing by business domain presupposes that you know the domains. If the feature set is still moving week to week, the slice boundaries you draw today are the ones you will redraw tomorrow, and the layer discipline adds ceremony without a payoff.

There is also a versioning consideration. The stable release is v2.0.0 from 2023-10-01, and the README states that the project became version-tracked from that point. v2.1 arrived on 2024-11-13 with the "Pages come first!" change. Tutorials and blog posts written against v2.0-beta, released 2021-05-17, may describe a structure that no longer matches.

Feature-Sliced Design compared with a single shared component library

The natural alternative for many teams is a shared component library plus feature folders: one package of reusable UI primitives, consumed by folders named after features, with no formal rule about who may import whom. The difference is not the folder names. It is that a component library governs reuse of presentation, while FSD governs the direction of dependencies across the whole application.

In a shared component library, a feature folder can import from another feature folder, and nothing stops a low-level utility from importing a page-level module. Over time the graph becomes bidirectional and the library's dependency edges become unreadable. FSD's answer is the rank rule: same layer and higher layers are off limits. That makes the graph acyclic by construction rather than by convention.

The trade-off runs the other way too. A component library has a concrete artifact, a version, and a changelog you can pin. FSD has a documented set of rules and a site. You get a mental model instead of a dependency, which is cheaper to adopt but easier to abandon halfway. Teams that need a hard boundary will have to write it themselves, and teams that want a drop-in solution will find that this repository does not provide one.

Maintenance, licensing and the cost of following a moving methodology

The repository is MIT licensed, which permits use, modification and redistribution with the licence and copyright notice preserved. That covers the documentation text and the site source. It does not grant anything about your own application code, and it is not legal advice; if you plan to republish the documentation content, read the LICENSE file at the repository root rather than relying on the SPDX identifier.

The repository is not archived, and the last push was on 2026-09-23, so the documentation is being edited regularly. The release cadence is slower than the commit cadence: v2.0.0 landed on 2023-10-01, v2.1 on 2024-11-13, and no later release appears in the release list. That means the site can change between releases, and a page you read today may not correspond to the newest tagged version.

Upgrade cost is mostly cognitive rather than mechanical. There is no package to bump in your application. The cost shows up when a new version reorders the layers or changes what comes first, as v2.1 did with pages. Budget for re-reading the relevant pages at fsd.how after each release and for revisiting your own folder structure when the guidance moves. The repository's own toolchain is also not trivial: Node 22 or newer, pnpm 10.17.1, Astro 5 and Starlight, plus a lint and format stack, so contributing to the docs means matching that environment.

Editorial conclusion

Adopt FSD if your team needs a shared vocabulary for splitting frontend code by business domain and can commit to the layer dependency rule, since that rule is what the methodology rests on. Do not adopt it if you are looking for a package to install: feature-sliced/documentation is a docs site, and the README states the methodology is not tied to a particular stack, so every enforcement mechanism is yours to build. Before committing, read the v2.1 release note that puts pages first, check the current layer list at fsd.how, and confirm your build tool can express the import restrictions you intend to enforce.

Frequently asked questions

Official sources

1. feature-sliced/documentation on GitHub
2. License: MIT
3. Project website
4. README
5. Releases