React Folder Structure

Table of Contents +

In the last lesson, React Suspense, you wrapped up the advanced patterns module. Now let’s organize a React project’s folder structure so your app stays easy to navigate as it grows.

🤔 Why does folder structure matter?

A small app with ten files is fine in one folder. But apps grow, and a flat pile of files becomes a mess.

You waste time hunting for the file you need among dozens of unrelated ones.
Related files (a component, its styles, its test) end up scattered far apart.
New people on the project can’t tell where anything lives or where new code should go.
Moving or deleting a feature means touching files all over the place.

So a good structure is about findability and change. Things that belong together live together.

🗂️ Two common approaches

There are two main ways people organize React projects, and knowing both helps you pick.

Group by type: all components in one folder, all hooks in another, all utils in another.
Group by feature: each feature has its own folder holding its components, hooks, and utils together.

So the choice is this: organize by what a file is, or by what part of the app it belongs to. Each fits a different size of project.

📁 Group by type

The simplest structure groups files by what they are. It’s good for small to medium apps.

src/
  components/    // all components
  hooks/         // all custom hooks
  utils/         // helper functions
  pages/         // route pages
  App.jsx
  main.jsx

Here’s how this feels to use.

Everything of one kind is in one place, so a new hook always goes in hooks/.
It’s simple and obvious, with no decisions about which feature a file belongs to.
But as the app grows, components/ can fill with hundreds of unrelated files.
Files for one feature get spread across components/, hooks/, and utils/.

So group-by-type is great while the app is small. It starts to strain once you have many features and the folders get crowded.

🧩 Group by feature

For larger apps, grouping by feature keeps everything for one part of the app together.

src/
  features/
    auth/
      LoginForm.jsx
      useAuth.js
      authApi.js
    dashboard/
      Dashboard.jsx
      useStats.js
      statsApi.js
  components/     // shared components used across features
  utils/          // shared helpers
  App.jsx

Here’s why this scales better.

Everything for auth (its component, hook, and API calls) lives in one folder.
To work on a feature, you open one folder and see all its pieces.
Adding or removing a feature means adding or removing one folder.
Truly shared things, like a reusable button, still live in a top-level components/.

Feature folders scale

As an app grows, grouping by feature usually wins. Everything related to one part of the app is in one place, so it’s easy to find, change, and even delete a whole feature at once. Keep genuinely shared pieces in shared folders.

🎯 Which should you use?

Don’t overthink it. Match the structure to the size of the app.

Small app or just learning: group by type, since it’s simple and clear.
Larger app with many distinct features: group by feature, with shared folders for common pieces.
Either way, keep it consistent. A predictable structure beats a clever one.

So start simple with group-by-type, then shift toward feature folders as the app grows and the type folders get crowded.

⚠️ Common Mistakes

The most common mistake is no structure at all, with everything dumped in one folder.

// ❌ everything in src/ root - chaos as it grows
src/
  App.jsx
  Login.jsx
  Dashboard.jsx
  useAuth.js
  api.js
  helpers.js
  Button.jsx
  ... 50 more files

// ✅ even simple grouping helps a lot
src/
  components/
  hooks/
  utils/
  pages/

Keep these in mind.

Don’t dump everything in the src root. Even basic folders help a lot.
Don’t over-engineer a tiny app with deep nested folders it doesn’t need.
Don’t mix approaches randomly. Pick one and be consistent.

✅ Best Practices

A few habits for folder structure.

Start with group-by-type for small apps, then move to feature folders as it grows.
Keep genuinely shared components, hooks, and utils in clear top-level shared folders.
Be consistent, so anyone can predict where a file lives.
Keep related files close, like a component with its styles and test.

There's no single right answer

React doesn’t force any structure, so teams choose their own. The best structure is the one your team agrees on and applies consistently. Findability and consistency matter more than following any one “perfect” layout.

🧩 What You’ve Learned

✅ A good folder structure keeps a growing app easy to find your way around
✅ Group by type puts all components, hooks, and utils in their own folders; simple for small apps
✅ Group by feature puts everything for one feature in one folder; scales better for larger apps
✅ Keep genuinely shared pieces in top-level shared folders either way
✅ Start simple and shift to feature folders as the app and its folders grow
✅ Consistency matters more than any single “perfect” structure

Check Your Knowledge

Test what you learned. Pick an answer for each question, then click Check.

🚀 What’s Next?

Now you can lay out a whole project sensibly. Next you’ll look at how to organize your components in particular, since they’re usually the largest part of a React app.