DEV Community

Cover image for Mastering Feature-Sliced Design: Lessons from Real Projects
Arjun
Arjun

Posted on

Mastering Feature-Sliced Design: Lessons from Real Projects

#architecture #frontend #nextjs #react

🌱 Intro

When building complex front-end applications, architecture decisions can make or break your project’s scalability. One approach that truly stood out to me after working on multiple React projects is Feature-Sliced Design (FSD) — a structured way to organize frontend code by features and business logic, not by file types.

After implementing FSD in production, I’ve seen how it can bring incredible clarity to large projects — but also how it can slow down smaller ones. This post breaks down my experience, what worked, what didn’t, and where I believe FSD really shines.

🧩 What Is Feature-Sliced Design?

Feature-Sliced Design (FSD) is an architectural methodology that helps organize frontend projects around business capabilities rather than UI elements or utilities.

Instead of grouping files like this:

src/
├── components/
├── hooks/
├── pages/
Enter fullscreen mode Exit fullscreen mode

FSD promotes a more domain-driven structure:

src/
├── app/
├── pages/
├── widgets/
├── features/
├── entities/
├── shared/
Enter fullscreen mode Exit fullscreen mode

Each layer represents a specific level of abstraction:

  • App → Application-level setup (providers, routing, config).
  • Pages → Route-level compositions.
  • Widgets → Complex UI blocks.
  • Features → Units of user-facing functionality.
  • Entities → Core domain logic or data models.
  • Shared → Common utilities and base components.

This hierarchy enforces direction — higher layers (like pages) can depend on lower layers (like entities), but not the other way around.

⚙️ How It Works in Practice

Let’s imagine a Fintech Dashboard — something similar to Revolut or Wise.

Using FSD, you might structure it like this:

src/
 ├─ app/
 │   └─ providers/
 │       ├─ AuthProvider.tsx
 │       └─ ThemeProvider.tsx
 ├─ pages/
 │   ├─ home/
 │   ├─ transactions/
 │   └─ payments/
 ├─ widgets/
 │   ├─ account-summary/
 │   └─ transaction-table/
 ├─ features/
 │   ├─ filter-transactions/
 │   ├─ make-payment/
 │   └─ export-statement/
 ├─ entities/
 │   ├─ user/
 │   └─ transaction/
 └─ shared/
     ├─ ui/
     ├─ api/
     └─ lib/
Enter fullscreen mode Exit fullscreen mode

Here’s what each layer does:

  • app/ – Setup code like providers and routing.
  • pages/ – Entry points connected to routes.
  • widgets/ – Complex UI blocks composed of multiple features or entities.
  • features/ – User-driven actions (e.g., filtering, exporting).
  • entities/ – Domain models like User, Account, or Transaction.
  • shared/ – Reusable utilities, UI components, and constants.

💡 My Experience Using FSD

In one of my recent React + Next.js projects, I used FSD to manage a financial transaction portal with multiple teams contributing to different modules.

Before adopting FSD, we constantly ran into issues like:

  • Unclear ownership of modules
  • Duplicated logic across pages
  • Difficulty in reusing UI components

After restructuring the app with FSD, we saw these key benefits:

  1. Separation of concerns — Teams could work on features/ and entities/ independently.
  2. High reusability — Shared logic (like authentication or API clients) became easier to reuse.
  3. Predictable structure — Every feature followed the same pattern, which made onboarding new developers faster.
  4. Clean imports — With proper path aliases, we avoided deep relative imports like ../../../Button.

A small but meaningful example:

We moved the “Download Report” feature into its own folder (features/download-report) — complete with its UI button with dropdown options, generating PDF logic, and hooks. Later, we reused that same feature on many listing pages without duplication. That kind of modularity simply wasn’t possible before.

🚀 Why It’s Great for Large Projects

When your project spans multiple domains or teams, FSD helps in three big ways:

1. Scalability

Each feature is self-contained — you can add or remove functionality without refactoring other parts.

2. Parallel Development

Different teams can safely work in parallel, since features are isolated.

3. Easy Abstraction

You can extract features or entities into a component library later with minimal changes.

For example, a shared auth module or a user entity can later be moved into an internal library for reuse across microfrontends.

📗 Read more: Understanding Layers in FSD

💡 Why I Found FSD Valuable in Large Projects

In one of my SaaS projects, we had multiple independent modules — Dashboard, Listing Page (with features like filtering and exporting), and Reports. Each module had its own logic, UI, and state management.

By applying FSD, each feature became a self-contained slice with clear boundaries. This had huge benefits:

  • Developers could work independently without touching unrelated parts of the codebase.
  • Each feature could later be published as a standalone package or reused in another project.
  • Refactoring became predictable — no mysterious side effects.

The level of reusability and modularity we achieved was far better than any flat folder structure could offer.

⚙️ Challenges and Real-World Lessons

While FSD works beautifully at scale, applying it effectively requires discipline and experience. Here are some lessons I learned along the way:

1. Defining Feature Boundaries Is Hard

The hardest part of FSD is figuring out where one feature ends and another begins. In theory, features should represent user actions like “log in” or “view reports.” But in practice, things like authentication, permissions, or logging don’t fit neatly into any one feature.

I learned to treat such cross-cutting concerns as infrastructure or shared context, not as individual features. This helps keep feature slices clean and focused.

2. Over-Slicing Early Is a Trap

Early in my FSD journey, I tried slicing everything — even small UI interactions. That quickly became unmanageable. Many slices were too small to justify their existence, and navigating the file tree became a chore.

The better approach was to start simple and slice only when the need arises. When a piece of functionality grows enough to deserve isolation, that’s when it becomes a feature.

3. Grouping Related Features Works — With Caution

For larger domains like Authentication, grouping sub-features (login, signup, reset password) made sense. But I also learned that grouping can blur boundaries if not carefully managed.

When a sub-feature grows beyond its parent domain, it’s often better to promote it into a standalone feature. Trying to over-organize can sometimes cause more friction than it solves.

4. The “Shared” Layer Can Become a Dumping Ground

Every team I’ve worked with eventually faces the same issue: the shared/ folder starts to collect everything. It’s easy to fall into the trap of putting unrelated utilities or UI elements there.

To avoid this, I adopted a simple rule — if it’s not reusable in multiple independent contexts, it doesn’t belong in shared/. That discipline helps prevent the “shared mess” problem that many large teams encounter.

5. It’s Not for Every Project Size

For small apps or prototypes, FSD is simply too much. Setting up layers and enforcing boundaries adds unnecessary boilerplate when your app only has a few pages.

I now apply FSD only when I know the project will grow — typically when working on SaaS platforms, dashboards, or modular systems. For smaller side projects, a simpler structure like Bulletproof React works perfectly.

🧠 Practical Tips That Worked for Me

  1. Introduce FSD gradually — don’t restructure everything at once.
  2. Keep feature definitions narrow — one clear responsibility per slice.
  3. Use lint rules like eslint-plugin-boundaries to enforce import order.
  4. Document the structure so the entire team follows the same conventions.
  5. Keep shared minimal — it should serve the app, not own it.

🚀 My Takeaway

Feature-Sliced Design is one of the most effective architectures I’ve used for scaling front-end projects. It encourages separation of concerns, reusability, and parallel development. However, it’s not a silver bullet.

In my experience:

✅ It excels in large, domain-heavy projects.

❌ It feels heavy-handed and slow in smaller applications.

If you expect your app to grow, FSD gives you a foundation that’s easy to maintain, scale, and evolve. If not, you might just be over-engineering the problem.

📚 Further Reading

Top comments (0)