Feature-Based Folder Structure for React Projects

A react folder structure that groups by feature puts the files that change together in one place. When one feature spans a components folder, a hooks folder, and a utils folder, a small change forces you to jump between unrelated directories.

Why file-type folders stop scaling

File-type folders group every component together and every hook together. That reads cleanly in a tutorial, but it separates the pieces of one feature.

A product list might need a component, a hook, a CSS file, and a test. In a file-type layout those live in four different top-level folders. Renaming or deleting the feature means touching all four places, and imports grow long because every path crosses the whole tree.

Group by feature

A feature folder owns everything a screen needs. Components, hooks, styles, and tests sit next to each other because they change together.

text

src/
  features/
    products/
      ProductList.jsx
      ProductFilters.jsx
      useProducts.js
      ProductList.test.jsx
    cart/
      CartDrawer.jsx
      useCart.js
  shared/
    Button.jsx
  main.jsx
  App.jsx

Each folder is a small, self-contained slice of the app. When the cart feature is removed, its folder goes with it and nothing else references the deleted files. The products folder can grow its own detail view, extra hooks, and subcomponents without forcing the cart feature to change.

Colocate what changes together

Inside a feature, keep the files that move in lockstep beside the component. A test for a list sits in the same folder as the list, and CSS Modules live beside the JSX they style. You read a feature as one unit instead of reconstructing it from five locations.

Colocation also shortens imports. A feature imports its own pieces with a relative path one level away, while a shared component is the only import that crosses a feature boundary.

App.jsx

import { ProductList } from "./ProductList";
import { useProducts } from "./useProducts";
import { Button } from "../../shared/Button";

The first two imports stay inside the feature. The third reaches into shared code, which makes the dependency visible.

Colocation also makes reviews easier. A change to the products feature stays inside one folder, so a pull request touches a few adjacent files instead of four separate directories. New team members can read one feature top to bottom without reconstructing how the pieces connect.

Share only what is truly shared

A shared folder is for code used by more than one feature. A button, a modal, or a formatting utility belongs there. Code used by a single feature should stay inside that feature even if it looks generic.

If two features need the same list filter, move it to shared only after the second use appears. Moving it early turns every future change into a cross-feature negotiation with no real benefit. This is the same principle behind separating business logic from React UI: keep code where its owner is clear.

Start from the Vite scaffold

A new Vite React project starts with a flat src folder holding App and main as entry points, which is the right size for the first screen or two. The default Vite project structure is intentionally minimal.

Introduce feature folders when a screen grows past a handful of files. Move the pieces for that screen into one folder, then repeat for the next screen.

Do not create empty folders for features you have not built yet. The structure should follow the work that exists, not a folder map copied from a larger project.

When not to over-structure

Check this list before adding more folders.

• Add a feature folder when a screen has several files that change together.
• Keep a file in shared only when at least two features use it.
• Avoid nesting more than two or three levels inside a feature.
• Prefer a flat feature folder until a single feature becomes genuinely large.

For setting up the project that this structure extends, see How to Create a React App with Vite.