📂 React Application Folder Structures: A Comprehensive Guide

A detailed exploration and comparison of the most effective and scalable folder structures for modern React applications. Choosing the right architecture is crucial for team velocity, maintainability, and long-term project health.

🌟 Motivation: Why Structure Matters

As a React application grows past a dozen components, the location of files directly impacts how quickly new features can be added and how easily bugs can be fixed.

A good folder structure helps development teams by:

• Improving Discoverability: Quickly find where a specific piece of logic (a component, a hook, a service) resides.

• Enforcing Consistency: Ensures all team members follow the same organisation pattern.

• Enhancing Scalability: Allows the app to grow without becoming a tangled mess of imports.

• Facilitating Refactoring: Makes it easier to safely move or delete features with minimal ripple effects.

🚀 React Structure Patterns

We analyze three primary patterns used in the industry, detailing the pros and cons of each.

🗂️ Component-Based Structure

A component-based (type-based) folder structure in React organises files based on their type or role within the application, promoting modularity and reusability.

src/
├── components/
│   ├── Button/
│   │   ├── Button.tsx             # The primary component file
│   │   ├── Button.css             # Local styles (or .module.css, .scss)
│   │   ├── Button.test.tsx        # Unit tests
│   │   ├── index.ts               # Exporting the component (facade)
│   │   └── types.ts               # TypeScript interfaces/props
│   ├── Card/
│   │   ├── Card.tsx
│   │   ├── Card.css
│   │   ├── index.ts
│   │   └── types.ts
│   ├── index.ts                   # Main export file for the *entire* library
│   └── shared-types.ts            # Global types used across components
├── hooks/                         # Any reusable hooks
├── utils/                         # Any reusable utilities
└── index.ts                       # Entry point for build tools (e.g., Webpack/Rollup)

🗂️ Component-Based Structure for project

src/
├── components/           // Reusable, generic components used throughout the application
│   ├── Button/
│   │   ├── Button.jsx
│   │   └── Button.module.css
│   ├── Card/
│   │   ├── Card.jsx
│   │   └── Card.module.css
│   └── ...
├── layout/               // Components specifically for application layout
│   ├── MainLayout/
│   │   ├── MainLayout.jsx
│   │   └── MainLayout.module.css
│   ├── Header/
│   │   ├── Header.jsx
│   │   └── Header.module.css
│   ├── Footer/
│   │   ├── Footer.jsx
│   │   └── Footer.module.css
│   └── ...
├── menu/                 // Components specifically for navigation menus
│   ├── MainMenu/
│   │   ├── MainMenu.jsx
│   │   └── MainMenu.module.css
│   ├── UserMenu/
│   │   ├── UserMenu.jsx
│   │   └── UserMenu.module.css
│   └── ...
├── pages/                // Top-level components representing distinct application pages/views
│   ├── HomePage/
│   │   ├── HomePage.jsx
│   │   └── HomePage.module.css
│   ├── AboutPage/
│   │   ├── AboutPage.jsx
│   │   └── AboutPage.module.css
│   └── ...
├── hooks/                // Custom React hooks
│   ├── useAuth.js
│   └── useDebounce.js
├── utils/                // Utility functions
│   ├── api.js
│   └── helpers.js
├── assets/               // Static assets (images, fonts, etc.)
│   ├── images/
│   └── fonts/
├── App.jsx               // Main application component
├── index.js              // Entry point of the application
└── styles/               // Global styles or theme variables
    ├── global.css
    └── variables.css

📌 Directory Overview

components/

Houses small, independent, and reusable UI components that can be used across different parts of the application (e.g., Button, Card, Input)

layouts/

Contains components responsible for the overall structure and arrangement of content on a page. This includes components like MainLayout (which might wrap the entire application content), Header, and Footer.

pages/

Represents distinct views or screens of the application. These components often compose other smaller components to form a complete page (e.g., HomePage, ProductPage).

hooks/

Stores custom React hooks for encapsulating reusable logic.

App.jsx

The root component that defines routing and layout selection.

index.js

Entry point of the React application where the React root is created and the app is mounted.

✅ Pros (Type-Based)

• Simple to Start: Easy for small projects and new developers to understand.

• Clear Technical Separation: If you know you're looking for a component, you go to components/.

❌ Cons (Type-Based)

• Poor Scalability: As the app grows, the components/ folder can become a massive, unmanageable list of hundreds of files.

• Feature Dispersal: Files related to a single feature (e.g., "User Profile") are spread across multiple top-level folders (components/ProfileButton, hooks/useProfileData, services/profileAPI).

🗂️ Feature-Based Structure

This approach groups all files related to a specific feature or domain into one self-contained folder. This is the recommended modern approach for medium-to-large applications.

src/
├── features/
│   ├── Auth/
│   │   ├── components/
│   │   │   ├── LoginForm.jsx
│   │   │   └── RegisterForm.jsx
│   │   ├── hooks/
│   │   │   └── useAuth.js
│   │   └── pages/
│   │       └── LoginPage.jsx
│   ├── Dashboard/
│   │   ├── components/
│   │   │   └── Widget.jsx
│   │   └── pages/
│   │       └── DashboardPage.jsx
│   └── ... (other features)
├── layouts/
│   ├── MainLayout.jsx
│   ├── AdminLayout.jsx
│   └── components/
│       ├── Header.jsx
│       ├── Sidebar.jsx
│       ├── Footer.jsx
│       └── Menu.jsx
├── shared/
│   ├── components/
│   │   ├── Button.jsx
│   │   └── Modal.jsx
│   ├── hooks/
│   │   └── useDebounce.js
│   └── utils/
│       └── helpers.js
├── App.jsx
├── index.js

📌 Directory Overview

features/

Contains isolated feature modules. Each module may include:

• Components
• Hooks
• Pages
• API logic
• Context or state management

layouts/

Houses global layout components that define structural UI for different app sections.

• MainLayout.jsx — used for general/public sections
• AdminLayout.jsx — used for admin-only sections
• layouts/components/ — structural UI elements shared across layouts (Header, Sidebar, Menu, etc.)

shared/

Contains fully reusable, truly generic utilities and UI elements designed to be used anywhere in the app.

App.jsx

The root component that defines routing and layout selection.

index.js

Entry point of the React application where the React root is created and the app is mounted.

✅ Pros (Feature-Based)

• High Cohesion (Feature Concentration): Everything you need for a feature is in one folder. Deleting a feature often means just deleting one directory.

• Reduced Scope Creep: Developers only need to worry about the files within their current feature directory.

• Excellent Scalability: Adding a new feature simply means creating a new top-level folder under features/.

❌ Cons (Feature-Based)

• Initial Overhead: Can feel overly complex for very small projects.

• Defining "Shared" vs. "Feature-Specific": Sometimes tricky to decide if a component belongs in a feature's subfolder or the global shared/components folder.

🤝 Contributing

Contributions are what make the open-source community an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project.

2. Create your Feature Branch (git checkout -b feature/AmazingFeature).

3. Commit your Changes (git commit -m 'Add some AmazingFeature').

4. Push to the Branch (git push origin feature/AmazingFeature).

5. Open a Pull Request.

📜 License

Distributed under the MIT License. See LICENSE for more information.