From Messy to Modular: React Folder Structures That Scale

Sometimes when working across different technologies, it's easy to forget why folder structure matters. I wrote this as a reminder — for myself and for you — of what a good project structure looks like when building with React. :)

First things first

React documentation have something to say about this too. They suggest to group files by using grouping by features or routes or by grouping by file type.

By file type:

api/
  APIUtils.js
  APIUtils.test.js
  ProfileAPI.js
  UserAPI.js
components/
  Avatar.js
  Avatar.css
  Feed.js
  Feed.css
  FeedStory.js
  FeedStory.test.js
  Profile.js
  ProfileHeader.js
  ProfileHeader.css

By features or routes:

common/
  Avatar.js
  Avatar.css
  APIUtils.js
  APIUtils.test.js
feed/
  index.js
  Feed.js
  Feed.css
  FeedStory.js
  FeedStory.test.js
  FeedAPI.js
profile/
  index.js
  Profile.js
  ProfileHeader.js
  ProfileHeader.css
  ProfileAPI.js

What companies use

Folder structure is often up for debate, and different companies follow different conventions. While structures may vary, there are some common patterns you’ll see across most React codebases — and it’s worth knowing what tends to stay consistent:

/components - Reusable UI components, sometimes with subfolders per component.
/context - React Context files for state management (e.g. Auth, Theme).
/hooks - Custom React hooks (useAuth, useFetch, etc).
/services - API logic and side effects (e.g. authService.ts, userService.ts).
/utils - Helper functions and pure utilities.
/assets - Images, icons, fonts, or other static files.
/config - App-wide constants, environment-specific settings.
/styles - Global styles or theme files (e.g. Tailwind config, CSS/SCSS).
/types - TypeScript type declarations (optional but useful).

🧱 Optional But Common Additions

These are more situational, but still appear often — especially in larger or more complex apps:

/api - For backend integration
/lib - General-purpose modules — often libraries that do not fit under utils or services.
/store - If you are using Redux or Zustand, this can hold your global state logic.
/pages - For routing frameworks
/features - Feature-based folder grouping for larger apps.

Note

Just like the React Docs, I believe in keeping things simple. Avoid unnecessary nesting — it may seem clean at first, but in larger projects, deep folder trees can get messy fast. Flat and modular often beats overly abstract. :)