React files and folder structure

Author

Miika Reijonen, Niko Laurila

Published

May 22, 2025

Modified

August 26, 2025

React Project File and Folder structure

A well-organized file and folder structure is crucial for the maintainability, scalability, and readability of a React frontend project. While React itself doesn’t enforce a specific structure, adopting a logical and consistent approach is highly recommended. Here’s a breakdown of common practices and guidelines:

Core Principles:

  • Clarity and Readability: The structure should be intuitive and easy for any developer to understand, even if they are new to the project.
  • Scalability: The structure should accommodate the growth of the application without becoming a tangled mess.
  • Maintainability: It should be easy to find and modify code, introduce new features, and refactor existing ones.
  • Separation of Concerns: Grouping related files together based on their purpose or feature helps keep the codebase organized.
  • Consistency: Once a structure is chosen, stick to it throughout the project.

Common Folder Structures:

Two prevalent approaches for organizing React projects are:

  1. Grouping by File Type: (should start by this)
    • Organizes files based on their technical role (e.g., all components in a components folder, all pages in a pages folder).
    • Simple and easy to grasp for smaller to medium-sized applications.
    • Can become harder to manage in large applications as feature logic is spread across different folders.
    src/
├── assets/ # images, fonts, icons
├── components/ # reusable UI components
├── pages/ # route-level components
├── utils/ # helper functions
├── hooks/ # custom React composables
├── tests/ # shared test utilities
├── App.ts
├── index.ts
└── ...
  2. Grouping by Feature (Domain-Based):
    • Organizes files based on the features or domains of the application (e.g., all files related to user authentication in an auth folder, all files related to products in a products folder).
    • More suitable for larger and complex applications.
    • Keeps feature-related logic and components together, improving maintainability and understanding of specific parts of the application.
    src/
├── features/
│   ├── auth/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── hooks/
│   │   ├── utils/
│   │   └── ...
│   └── products/
│       ├── components/
│       ├── pages/
│       ├── hooks/
│       ├── utils/
│       └── ...
├── components/ (for shared/global components)
├── assets/
├── utils/ (for shared utilities)
├── App.ts
└── index.ts

Many projects adopt a hybrid approach, combining aspects of both, which often proves effective for balancing simplicity and scalability.

Key Folders and their Organization:

Within the chosen structure, here’s a breakdown of common folders and how to organize files within them:

  • src/: This is the main directory for your application’s source code. Most of your development will happen here.
  • components/:
    • Houses reusable UI components that can be used across different parts of your application.
    • Can be further organized into subfolders for better grouping (e.g., components/buttons, components/forms, components/ui).
    • For feature-based structures, this folder is typically for truly global or shared components. Feature-specific components reside within the feature’s folder.
    • Consider grouping component-related files (component file, CSS/styled-components, tests) within a single folder named after the component (e.g., components/Button/Button.ts, components/Button/Button.module.css, components/Button/Button.test.ts).
  • pages/ (or routes/):
    • Contains top-level components that represent different pages or routes in your application.
    • These components typically compose smaller components from the components folder to form a complete page layout.
    • In frameworks like Next.ts, this folder has a specific meaning for file-system based routing. In create-react-app or similar setups using React Router, these are simply components rendered at specific routes.
  • assets/:
    • Stores static assets like images, fonts, and other media files.
    • Can be further categorized into subfolders like assets/images, assets/fonts, etc.
  • utils/:
    • Contains utility functions or helper modules that perform common tasks and are used across the application.
    • Examples include date formatting, API helpers, validation functions, etc.
  • hooks/:
    • Dedicated folder for custom React hooks.
    • Organizing custom hooks here makes them easily discoverable and reusable.
  • context/:
    • If you are using React’s Context API for state management, store your context providers and consumers here.
  • redux/ or store/:
    • If using Redux or another state management library, this folder will contain your store configuration, reducers, actions, and selectors.
    • Can be organized by feature or module within this folder.
  • styles/:
    • Contains global styles, CSS variables, theme files, or shared styling configurations.
    • If using CSS modules or styled-components, component-specific styles often live with the component files.
  • api/ or services/:
    • Houses modules responsible for interacting with backend APIs or external services.
    • Separating API logic makes it easier to manage data fetching and mutations.
  • constants/:
    • Stores application-wide constants.
  • types/ (for TypeScript projects):
    • Contains TypeScript type definitions and interfaces.

Organizing Pages and Routes:

  • Route Configuration: If you are using a routing library like React Router, the main route configuration can reside in your App.ts or in a dedicated routes.ts file within the src folder or a routes/ subfolder.
  • Page Components: As mentioned, place components that represent full pages in the pages/ folder (or within feature folders in a feature-based structure).
  • Nested Routes: For nested routes, the corresponding components can be organized hierarchically within the pages/ or feature folders to mirror the route structure.

Guidelines for File Naming:

  • Components: Use PascalCase (e.g., Button.ts, UserProfilePage.ts).
  • Other Files: Use camelCase or kebab-case depending on your team’s preference (e.g., utils.ts, api-client.ts).
  • Index Files: Using index.ts within a folder allows for cleaner imports (e.g., import Button from './components/Button') instead of import Button from './components/Button/Button'). However, this can make it harder to find specific files when searching in an editor. Choose one approach and stick to it.
  • Test Files: Colocate test files with the code they are testing, using a consistent naming convention (e.g., Button.test.ts, useAuth.test.ts).

Avoiding Common Pitfalls:

  • Too Much Nesting: Deeply nested folders can make navigation and imports cumbersome. Aim for a relatively flat structure where possible.
  • Inconsistent Naming: Lack of consistent naming conventions for files and folders can lead to confusion.
  • Mixing Concerns: Avoid putting unrelated logic or components in the same folder.
  • Over-engineering: Don’t create overly complex structures for small projects. Start simple and refactor as the project grows.

Choosing the Right Structure:

The “best” structure depends on the size and complexity of your project, as well as the preferences of your development team.

  • For small projects or those just starting, a file-type based structure is often sufficient and easy to get started with.
  • For medium to large projects with distinct features, a feature-based or hybrid approach generally provides better organization and scalability.

Discuss and agree on a structure with your team early in the project and document it. This ensures everyone is on the same page and helps maintain consistency as the project evolves.

Back to top