Introduction
scaling React apps gets messy quickly as they grow. Flat structures like components/, pages/, and hooks/ don’t scale well for real-world applications.
As your application grows, you’ll end up with hundreds of unrelated components and hooks dumped into global folders. Searching and maintaining becomes a nightmare.
What is Feature-Based Architecture?
Feature-Based Architecture is an organizational pattern where code is grouped by feature or domain, instead of by file type. In traditional React project structures, it’s common to see directories like components/, pages/, hooks/, and utils/ at the top level. This might work for small projects, but it quickly becomes hard to manage as the app grows.
In contrast, feature-based architecture groups all files related to a specific functionality (e.g., Posts, Products, Users) together in one directory. Each feature becomes a self-contained module with its own UI components, logic, hooks, types, tests, and even routing if needed.
🧩 Traditional Structure (By File Type)
src/
├── components/
│ ├── PostItem.tsx
│ ├── PostList.tsx
├── pages/
│ └── PostsPage.tsx
├── hooks/
│ └── usePost.ts
├── types/
│ └── post.types.ts
❌ This leads to scattered logic. If you’re working on „Posts“, you’ll jump across multiple folders to maintain or update code.
✅ Feature-Based Structure
├── core/ # Global configurations, assets, context providers, styles
│ ├── assets/
│ │ └── css/
│ │ └── App.css
│ └── config/ # App-wide config files (e.g., api config, constants)
│ └── env.ts
│
├── layouts/ # Application-level layouts
│ ├── Header.tsx
│ └── FullLayout.tsx
│
├── features/
│ └── Post/
│ ├── components/
│ │ ├── PostItem.tsx
│ │ └── PostList.tsx
│ ├── hooks/
│ │ └── usePost.ts
│ ├── types/
│ │ └── post.types.ts
│ ├── views/
│ │ └── PostView.tsx
│ └── routes.ts
│
├── router.ts # Application-wide routing
├── main.tsx # React entry point
└── index.html
📌 Notes
core/: This is where you put global, app-wide concerns that aren’t tied to a specific feature. Examples:
- Global CSS or theming
- API clients
- Context providers (like AuthProvider, ThemeProvider)
- Application configuration files (env.ts, routes.config.ts)
- layouts/: Layout components that define page structure (headers, sidebars, wrappers)
- features/: Each folder represents a self-contained domain, including everything that feature needs (UI, logic, routing, etc.)
🔍 With this layout, the root-level src/ is clean and clearly segmented into global utilities (core/, layouts/) and isolated business logic (features/).
📦 Example Repository
To help you get started, I’ve built a sample boilerplate using the exact structure described in this article.
You can check it out on GitHub:
👉 https://github.com/naserrasoulii/feature-based-react
Feel free to fork it, use it as a base for your own projects, or contribute improvements!