DEV Community: Arjun

Mastering Feature-Sliced Design: Lessons from Real Projects

Arjun — Mon, 03 Nov 2025 21:11:50 +0000

🌱 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/

FSD promotes a more domain-driven structure:

src/
├── app/
├── pages/
├── widgets/
├── features/
├── entities/
├── shared/

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/

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:

Separation of concerns — Teams could work on features/ and entities/ independently.
High reusability — Shared logic (like authentication or API clients) became easier to reuse.
Predictable structure — Every feature followed the same pattern, which made onboarding new developers faster.
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

Introduce FSD gradually — don’t restructure everything at once.
Keep feature definitions narrow — one clear responsibility per slice.
Use lint rules like eslint-plugin-boundaries to enforce import order.
Document the structure so the entire team follows the same conventions.
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

Official documentation: https://feature-sliced.design/
ESLint boundaries plugin: https://www.npmjs.com/package/eslint-plugin-boundaries

Building Our Own `create-app` CLI — A Custom NPX Script for Fast Project Bootstrapping

Arjun — Fri, 31 Oct 2025 20:18:20 +0000

Intro

When our team began building multiple web applications using Next.js, we didn’t initially think about creating a CLI tool. We just wanted to ship products fast and maintain a consistent development experience across projects. But as the number of products grew, we realized that setting up each new application from scratch was repetitive, time-consuming, and error-prone.

This is the story of how we built our own custom npx script, inspired by tools like create-next-app, to help our developers spin up new projects instantly — complete with our in-house configurations, libraries, and folder structure.

The Beginning: From One App to Many

It started with one app.

Then came another.

And soon, several more.

Our frontend team was responsible for building multiple product UIs for different internal and customer-facing tools. We were using Next.js as our primary framework, following the Feature-Sliced Design (FSD) methodology — an architectural pattern that helps organize frontend projects into clear, maintainable layers.

Each new app required:

Installing common dependencies (like our in-house component and utility libraries).
Setting up authentication logic.
Maintaining a consistent folder structure (based on FSD).
Applying our own ESLint, Prettier, and Husky configurations.
Enforcing a consistent code style and commit rules across repositories.

After a few projects, we realized we were spending too much time doing setup work that could easily be automated.

The Starter Template

So we created a starter template — a cleaned-up, minimal Next.js app that included all our standard configurations and base dependencies.

It served as a “bare minimum” project — something new developers could clone and start coding right away. The template included:

✅ Next.js setup with TypeScript
✅ Pre-configured ESLint, Prettier, and Husky
✅ Authentication boilerplate
✅ FSD folder structure (src/app, src/entities, src/features, etc.)
✅ In-house component and utility libraries
✅ Git hooks for linting and formatting

This helped us a lot initially. But soon, as more developers joined and new types of projects emerged (like prototype apps to test UI designs quickly), managing multiple starter templates manually became difficult.

That’s when we decided to take it one step further.

The Idea: A Custom `npx` Script Like `create-next-app`

We wanted to give our developers a simple command like:

npx create-our-app my-new-project --template=starter

or for prototype apps:

npx create-our-app my-proto-project --template=proto

The goal was to automate:

Creating a new project directory.
Copying the correct template files.
Installing dependencies.
Setting up git, linting, and formatting.
Applying our team’s coding standards automatically.

Essentially, we wanted something that felt like create-next-app, but fully tailored to our ecosystem.

The Technical Implementation

We took inspiration from Vercel’s create-next-app repository. It’s a great reference for building custom NPX tools, and its structure made a lot of sense.

Our project followed a similar layout:

create-our-app/
├── templates/
│   ├── starter/
│   ├── proto/
│   └── common/
├── src/
│   ├── helpers/
│   │   ├── downloadTemplate.ts
│   │   ├── copyTemplateFiles.ts
│   │   ├── installDependencies.ts
│   │   └── log.ts
│   └── index.ts
├── package.json
└── tsconfig.json

The index.ts file serves as the entry point — it handles argument parsing, project name validation, and calls helper functions for each setup step.

Setting Up package.json for a CLI Tool

To make your CLI runnable with npx or after a global install, you need to configure the bin field in your package.json.
This field tells Node.js which file to execute when the command is called.

Example:

{
  "name": "create-our-app",
  "version": "1.0.0",
  "description": "A custom NPX script to bootstrap frontend projects with our starter templates",
  "bin": {
    "create-our-app": "dist/index.js"
  },
  "type": "module",
  "files": [
    "dist"
  ],
  "repository": {
    "type": "git",
    "url": "https://github.com/our-org/create-our-app.git"
  },
  "author": "Your Team Name",
  "license": "MIT",
  "dependencies": {
    "commander": "^11.0.0",
    "inquirer": "^9.0.0",
    "fs-extra": "^11.1.1",
    "tar": "^6.2.0"
  }
}

Explanation:

bin — maps your command name (create-our-app) to the executable file (after it’s built, e.g., dist/index.js).
type — ensures Node treats your project as an ES module (if using ES imports).
files — limits which files are published to npm (here, only dist).
repository — links the CLI’s GitHub repo for transparency and easy access.

Once this is set up and you’ve built your project, you can test it locally with:

npm link

Then you can run your CLI globally using:

create-our-app my-app

Argument Parsing

We used the commander library for parsing CLI arguments. It made it easy to handle flags like --template, --use-npm, or --git.

import { Command } from "commander";
const program = new Command();

program
  .name("create-our-app")
  .description("Initialize a new frontend project with our custom setup")
  .option("-t, --template <template>", "Choose a template", "starter")
  .option("--use-npm", "Use npm instead of yarn")
  .parse(process.argv);

Interactive Prompts with Inquirer

We also integrated inquirer to make the CLI interactive.

If a user skips the CLI arguments (like template name or package manager), the script automatically prompts them with questions.

Example:

import inquirer from "inquirer";

const answers = await inquirer.prompt([
  {
    type: "list",
    name: "template",
    message: "Choose a project template:",
    choices: ["starter", "proto"],
    default: "starter",
  },
  {
    type: "list",
    name: "pkgManager",
    message: "Select a package manager:",
    choices: ["npm", "yarn", "pnpm"],
    default: "npm",
  },
]);

Downloading Templates

For flexibility, we wanted developers to pass a GitHub URL instead of just using built-in templates.

For example:

npx create-our-app my-app --template=https://github.com/our-org/custom-template

To achieve that, we used tarball downloads from GitHub’s codeload API:

const url = `https://codeload.github.com/${username}/${repo}/tar.gz/${branch}`;

We then extracted the tar file using the tar package, which let us clone only the needed files instead of pulling the entire Git history.

Copying Local Templates

If a local template was used, we relied on fs-extra for copying directories recursively. This library also helped us handle file overwrites and cleanups safely.

import fs from "fs-extra";

await fs.copy(
  path.join(__dirname, `../templates/${template}`),
  targetDirectory
);

Installing Dependencies

After copying the template, the script automatically installed dependencies using either npm, yarn, or pnpm — depending on what the developer preferred or had installed.

import { execSync } from "child_process";

execSync(`${pkgManager} install`, { stdio: "inherit" });

The Result: Developer Happiness 😄

After introducing our custom CLI, onboarding new developers became seamless.

Instead of sharing long setup instructions, we just gave them a single command. Within a couple of minutes, they had a fully configured Next.js project with all our defaults in place.

Some key benefits we noticed:

⚡ Faster onboarding — No more copy-pasting config files.
🔒 Consistency — Every project follows the same structure and rules.
🧩 Scalability — Adding new templates (e.g., mobile dashboard, prototype app) is easy.
🔧 Maintainability — Centralized control over shared tooling and updates.

Lessons Learned

A few things we learned while building this:

Start simple — the first version doesn’t need every feature.
Document every flag and template — new developers will thank you later.
Avoid making assumptions about the environment (e.g., which package manager is installed).
Use meaningful logs and color-coded output for better CLI UX (we used chalk for this).
Always clean up temporary files and handle errors gracefully.

What’s Next

We’re planning to add:

More interactive prompts for optional modules (like auth, analytics, or feature toggles).
Remote template versioning for better maintainability.

The journey of building this tool taught us that developer experience (DX) is as important as user experience. By investing a bit of time in tooling, we saved countless hours for our team and made development far more consistent and enjoyable.

In short:

Our custom npx script started as a small internal experiment but quickly became one of the most impactful productivity tools in our development workflow.

Custom Build folder for React

Arjun — Fri, 24 Dec 2021 23:48:56 +0000

🧱 How to Change the Build Path in a React Application

Sometimes you may want your React app’s build output to be moved to a different directory — for example, into a server’s public folder. In this guide, we’ll see how to do that using a simple shell script that runs automatically after the build process.

🪶 Step 1: Create a Shell Script

Create a new shell script file named {file-name}.sh inside the root directory of your React project.

🪶 Step 2: Update `package.json`

Open your package.json file and add a new script named postbuild right below the existing build script:

"scripts": {
  "start": "react-scripts start",
  "build": "react-scripts build",
  "postbuild": "./{file-name}.sh"
}

💡 Note:

If you’re on Windows, make sure you have Git Bash or WSL installed to run the script, since native Command Prompt doesn’t support bash syntax.

You can run it manually using:

bash {file-name}.sh

🪶 Step 3: Write the Shell Script

The shell script will move your built files to a new directory after every build.

Here’s a sample script you can modify as needed:

#!/bin/bash

# Define your app name or set it as an environment variable
APP_NAME="my-react-app"

# If the target folder exists, remove its contents first, then move the new files
if [ -d "./../server/public/${APP_NAME}/" ]; then
    echo "Target folder exists. Cleaning it..."
    rm -rv ./../server/public/${APP_NAME}/*
    # Move the build files (use cp -r instead of mv if you want to keep a copy)
    mv -v build/* ./../server/public/${APP_NAME}/
else
    # Otherwise, create the target folder and then move the files
    echo "Creating target folder and moving files..."
    mkdir -p ./../server/public/${APP_NAME}
    mv -v build/* ./../server/public/${APP_NAME}/
fi

🧩 Tip:

mv moves the files (the build folder will be emptied afterward).

Use cp -r instead if you prefer to copy the files and keep the original build intact.

🧩 How It Works

When you run:

npm run build

React completes its build process and then automatically executes the postbuild script.

This script checks if the target directory already exists:

✅ If it exists — the folder is cleared, and new build files are moved in.
🆕 If not — it creates the folder and moves the files.

⚠️ Make sure your project structure matches this example:
/my-project
├── react-app/
└── server/
Adjust the relative path (./../server/public/) if your setup differs.

🧠 Customize It

You can tweak this script for your own directory structure or workflow.

To explore more possibilities, check out a few beginner-friendly shell scripting tutorials — you’ll be surprised how much you can automate.

🎉 Final Thoughts

That’s it! With this small setup, your React app’s build files will automatically be relocated right after each build — no manual steps needed.

Happy Coding! 🥳