React project structure

A well-organized project structure is crucial for code maintainability, easy navigation, and scalability of React applications. In this module, we'll look at best practices for structuring React projects and understand how to organize files and components.

Basic React project structure

Regardless of whether you use Create React App, Vite, or another tool, the basic structure of a React project usually looks similar:

1my-react-project/
2├── node_modules/        # Installed dependencies
3├── public/              # Publicly accessible static files
4├── src/                 # Application source code
5│   ├── components/      # Reusable components
6│   ├── pages/           # Components representing entire pages
7│   ├── assets/          # Assets such as images, fonts, etc.
8│   ├── utils/           # Utility functions
9│   ├── services/        # Code responsible for API communication
10│   ├── hooks/           # Custom React hooks
11│   ├── context/         # React contexts
12│   ├── App.js           # Main application component
13│   └── index.js         # Application entry point
14├── .gitignore           # Files ignored by Git
15├── package.json         # Project info and dependencies
16└── README.md            # Project documentation

Let's discuss the most important directories and their purposes:

The src/ directory

The

src/

directory is the heart of your React application. It contains all the logic, components, and assets. Here's how this directory is typically organized:

components/

Contains reusable components that are used in various parts of the application. There are several approaches to structuring components:

Flat structure

1components/
2├── Button.jsx
3├── Button.css
4├── Header.jsx
5├── Header.css
6├── Footer.jsx
7└── Footer.css

Grouped structure (preferred for larger projects)

1components/
2├── Button/
3│   ├── Button.jsx
4│   ├── Button.css
5│   └── index.js
6├── Header/
7│   ├── Header.jsx
8│   ├── Header.css
9│   └── index.js
10└── Footer/
11    ├── Footer.jsx
12    ├── Footer.css
13    └── index.js

Using

index.js

files to export components simplifies imports:

1// Instead of:
2import Button from './components/Button/Button';
3
4// You can write:
5import Button from './components/Button';

pages/

Components representing entire pages or views in the application. In projects with routing, each file in this directory typically corresponds to a specific URL path:

1pages/
2├── Home/
3│   ├── Home.jsx
4│   └── Home.css
5├── About/
6│   ├── About.jsx
7│   └── About.css
8└── Dashboard/
9    ├── Dashboard.jsx
10    └── Dashboard.css

assets/

Contains all static assets used in the application:

1assets/
2├── images/
3│   ├── logo.png
4│   └── background.jpg
5├── fonts/
6│   ├── roboto.ttf
7│   └── open-sans.ttf
8└── styles/
9    ├── variables.css
10    └── global.css

utils/

Utility functions and tools used throughout the application:

1utils/
2├── formatDate.js
3├── validation.js
4└── helpers.js

services/

Code responsible for communicating with external APIs or services:

1services/
2├── api.js           # Basic API configuration
3├── userService.js   # User-related queries
4└── productService.js # Product-related queries

hooks/

Custom React hooks that can be used in multiple places in the application:

1hooks/
2├── useLocalStorage.js
3├── useFetch.js
4└── useForm.js

context/

React contexts used for managing global state:

1context/
2├── AuthContext.js
3├── ThemeContext.js
4└── CartContext.js

Organization by feature vs. by type

There are two main approaches to code organization:

Organization by type (shown above)

Files are grouped by their type (components, hooks, services, etc.).

Organization by feature

Files are grouped by feature or part of the application:

1src/
2├── auth/
3│   ├── components/
4│   ├── hooks/
5│   ├── services/
6│   └── context/
7├── products/
8│   ├── components/
9│   ├── hooks/
10│   ├── services/
11│   └── utils/
12└── checkout/
13    ├── components/
14    ├── hooks/
15    └── services/

This structure is more scalable for large projects, especially when multiple people are working on them.

Naming conventions

Consistent naming is just as important as directory structure:

Components

• Use PascalCase:

  Button.jsx

  ,

  UserProfile.jsx

• JSX files should have the

  .jsx

  extension (not required, but helps with identification)

Hooks

• Always start with "use":

  useLocalStorage.js

  ,

  useWindowSize.js

Contexts

• Usually end with "Context":

  AuthContext.js

  ,

  ThemeContext.js

Services and utilities

• Use camelCase:

  apiService.js

  ,

  formatDate.js

Styles in React

There are several approaches to organizing styles in React:

CSS Modules

1Button/
2├── Button.jsx
3└── Button.module.css

Styled Components

1Button/
2└── Button.jsx  # Contains styled-components definitions

SCSS/SASS

1Button/
2├── Button.jsx
3└── Button.scss

Folder structure best practices

In the React cosmic fleet, a well-organized folder structure is like an efficient logistics system on a spaceship - everything has its place and you can quickly find what you need. Here are proven practices for organizing React projects.

Feature-based vs Type-based organization

Two main approaches to organizing code in React projects:

Type-based organization

Files grouped by their technical role - all components together, all hooks together, etc.

1src/
2├── components/
3│   ├── Button/
4│   ├── Card/
5│   ├── Modal/
6│   ├── UserProfile/
7│   ├── ProductCard/
8│   └── ShoppingCart/
9├── hooks/
10│   ├── useAuth.js
11│   ├── useProducts.js
12│   └── useCart.js
13├── services/
14│   ├── authService.js
15│   ├── productService.js
16│   └── cartService.js
17└── utils/
18    ├── validators.js
19    └── formatters.js

Advantages:

• Simpler for small and medium projects
• Easy to understand for new developers
• Good for SPA applications without distinct modules

Disadvantages:

• In large projects, it's hard to find all files related to a single feature
• Components from different features are mixed together
• Harder to scale across teams

Feature-based organization

Files grouped by business feature - all files related to authentication together, all product-related files together, etc.

1src/
2├── features/
3│   ├── auth/
4│   │   ├── components/
5│   │   │   ├── LoginForm/
6│   │   │   ├── RegisterForm/
7│   │   │   └── PasswordReset/
8│   │   ├── hooks/
9│   │   │   ├── useAuth.js
10│   │   │   └── useSession.js
11│   │   ├── services/
12│   │   │   └── authService.js
13│   │   ├── utils/
14│   │   │   └── validators.js
15│   │   └── index.js
16│   │
17│   ├── products/
18│   │   ├── components/
19│   │   │   ├── ProductList/
20│   │   │   ├── ProductCard/
21│   │   │   └── ProductDetails/
22│   │   ├── hooks/
23│   │   │   ├── useProducts.js
24│   │   │   └── useProductFilters.js
25│   │   ├── services/
26│   │   │   └── productService.js
27│   │   └── index.js
28│   │
29│   └── cart/
30│       ├── components/
31│       │   ├── ShoppingCart/
32│       │   ├── CartItem/
33│       │   └── Checkout/
34│       ├── hooks/
35│       │   └── useCart.js
36│       ├── services/
37│       │   └── cartService.js
38│       └── index.js
39│
40├── shared/
41│   ├── components/
42│   │   ├── Button/
43│   │   ├── Modal/
44│   │   └── Card/
45│   ├── hooks/
46│   │   ├── useLocalStorage.js
47│   │   └── useDebounce.js
48│   └── utils/
49│       ├── formatDate.js
50│       └── formatCurrency.js
51│
52└── App.jsx

Advantages:

• Easier to scale for large projects
• All files related to a feature are in one place
• Easier for team work (different teams can work on different features)
• Easier to remove entire features
• Better for code splitting

Disadvantages:

• More complex for beginners
• Requires more thought in design
• Can lead to duplication for very small components

Naming conventions

Consistent naming is a key element of a well-organized project. In React, the following conventions apply:

Components - PascalCase

1// GOOD - PascalCase
2Button.jsx
3UserProfile.jsx
4ShoppingCart.jsx
5ProductCard.jsx
6
7// BAD - other conventions
8button.jsx
9user-profile.jsx
10shopping_cart.jsx

Why PascalCase?

• Distinguishes React components from regular functions
• Convention adopted across the entire React ecosystem
• JSX requires PascalCase for components (custom tags)

Hooks - camelCase with "use" prefix

1// GOOD - camelCase with "use"
2useAuth.js
3useLocalStorage.js
4useWindowSize.js
5useProductFilters.js
6
7// BAD - missing "use" or wrong convention
8Auth.js
9local-storage.js
10WindowSize.js

Why "use" prefix?

• React requires custom hooks to start with "use"
• Allows React to validate hook rules
• Immediately communicates that it's a hook

Contexts - PascalCase with "Context" suffix

1// GOOD - PascalCase with "Context"
2AuthContext.js
3ThemeContext.js
4CartContext.js
5UserPreferencesContext.js
6
7// BAD - missing "Context" or wrong convention
8auth.js
9theme-context.js
10Cart.js

Utils and services - camelCase

1// GOOD - camelCase
2formatDate.js
3validateEmail.js
4apiService.js
5authService.js
6
7// BAD - other conventions
8FormatDate.js
9validate-email.js
10API_Service.js

Where to keep different file types

Planning file locations in a project has enormous significance for its readability and scalability.

Hooks (custom hooks)

Feature-based approach:

1features/
2├── auth/
3│   └── hooks/
4│       ├── useAuth.js
5│       └── useSession.js
6└── products/
7    └── hooks/
8        └── useProducts.js
9
10shared/
11└── hooks/
12    ├── useLocalStorage.js  # Shared hook
13    ├── useDebounce.js      # Shared hook
14    └── useFetch.js         # Shared hook

Type-based approach:

1hooks/
2├── useAuth.js
3├── useSession.js
4├── useProducts.js
5├── useLocalStorage.js
6├── useDebounce.js
7└── useFetch.js

Utils (utility functions)

Feature-based approach:

1features/
2├── products/
3│   └── utils/
4│       ├── formatPrice.js
5│       └── filterProducts.js
6└── auth/
7    └── utils/
8        └── validatePassword.js
9
10shared/
11└── utils/
12    ├── formatDate.js       # Shared
13    ├── debounce.js         # Shared
14    └── cloneDeep.js        # Shared

Type-based approach:

1utils/
2├── formatPrice.js
3├── formatDate.js
4├── validatePassword.js
5├── filterProducts.js
6├── debounce.js
7└── cloneDeep.js

Types (TypeScript)

If you use TypeScript, you have several options for types:

Option 1: Next to the files that use them:

1components/
2└── Button/
3    ├── Button.tsx
4    ├── Button.types.ts     # Types only for Button
5    ├── Button.styles.ts
6    └── index.ts

Option 2: Centralized types:

1types/
2├── user.types.ts
3├── product.types.ts
4├── cart.types.ts
5└── api.types.ts

Option 3: Hybrid (best):

1features/
2└── products/
3    ├── components/
4    ├── types/              # Feature-specific types
5    │   ├── product.types.ts
6    │   └── filter.types.ts
7    └── index.ts
8
9shared/
10└── types/                  # Shared types
11    ├── common.types.ts
12    └── api.types.ts

Example project structure - best practices

Combining feature-based for main features and type-based for shared resources:

1my-react-app/
2├── public/
3├── src/
4│   ├── features/                    # Main features
5│   │   ├── auth/
6│   │   │   ├── components/
7│   │   │   │   ├── LoginForm/
8│   │   │   │   │   ├── LoginForm.tsx
9│   │   │   │   │   ├── LoginForm.styles.ts
10│   │   │   │   │   ├── LoginForm.test.tsx
11│   │   │   │   │   └── index.ts
12│   │   │   │   └── RegisterForm/
13│   │   │   ├── hooks/
14│   │   │   │   ├── useAuth.ts
15│   │   │   │   └── useSession.ts
16│   │   │   ├── services/
17│   │   │   │   └── authService.ts
18│   │   │   ├── types/
19│   │   │   │   └── auth.types.ts
20│   │   │   └── index.ts
21│   │   │
22│   │   ├── products/
23│   │   │   ├── components/
24│   │   │   │   ├── ProductList/
25│   │   │   │   ├── ProductCard/
26│   │   │   │   └── ProductFilters/
27│   │   │   ├── hooks/
28│   │   │   │   ├── useProducts.ts
29│   │   │   │   └── useProductFilters.ts
30│   │   │   ├── services/
31│   │   │   │   └── productService.ts
32│   │   │   ├── types/
33│   │   │   │   └── product.types.ts
34│   │   │   └── index.ts
35│   │   │
36│   │   └── cart/
37│   │       └── [similar structure]
38│   │
39│   ├── shared/                      # Shared resources
40│   │   ├── components/
41│   │   │   ├── Button/
42│   │   │   │   ├── Button.tsx
43│   │   │   │   ├── Button.styles.ts
44│   │   │   │   ├── Button.test.tsx
45│   │   │   │   └── index.ts
46│   │   │   ├── Modal/
47│   │   │   ├── Card/
48│   │   │   └── Layout/
49│   │   │
50│   │   ├── hooks/
51│   │   │   ├── useLocalStorage.ts
52│   │   │   ├── useDebounce.ts
53│   │   │   └── useFetch.ts
54│   │   │
55│   │   ├── utils/
56│   │   │   ├── formatDate.ts
57│   │   │   ├── validators.ts
58│   │   │   └── helpers.ts
59│   │   │
60│   │   ├── types/
61│   │   │   ├── common.types.ts
62│   │   │   └── api.types.ts
63│   │   │
64│   │   └── constants/
65│   │       ├── routes.ts
66│   │       └── config.ts
67│   │
68│   ├── layouts/                     # Layout components
69│   │   ├── MainLayout/
70│   │   ├── AuthLayout/
71│   │   └── DashboardLayout/
72│   │
73│   ├── pages/                       # Page components (for routing)
74│   │   ├── HomePage/
75│   │   ├── ProductsPage/
76│   │   ├── ProductDetailPage/
77│   │   └── CartPage/
78│   │
79│   ├── context/                     # Global contexts
80│   │   ├── AuthContext.tsx
81│   │   ├── ThemeContext.tsx
82│   │   └── CartContext.tsx
83│   │
84│   ├── router/                      # Routing configuration
85│   │   ├── routes.tsx
86│   │   └── ProtectedRoute.tsx
87│   │
88│   ├── styles/                      # Global styles
89│   │   ├── globals.css
90│   │   ├── variables.css
91│   │   └── reset.css
92│   │
93│   ├── App.tsx
94│   └── index.tsx
95│
96├── .eslintrc.js
97├── .prettierrc
98├── tsconfig.json
99├── package.json
100└── README.md

File organization rules

1. Maximum 3 levels rule
   • Avoid nesting deeper than 3 levels
   • If you need more, your structure is probably too complex

1// GOOD - 3 levels
2src/features/products/components/
3
4// BAD - too deep
5src/modules/ecommerce/features/products/ui/components/

2. Export through index.ts
   • Every folder with a component has an index.ts
   • Simplifies imports and hides implementation details

1// components/Button/index.ts
2export { default } from './Button';
3export * from './Button.types';
4
5// Usage
6import Button from './components/Button';  // readable
7// instead of
8import Button from './components/Button/Button';  // verbose

3. Colocation - keep together what is used together
   • Styles next to the component
   • Tests next to the component
   • Types next to the component

1Button/
2├── Button.tsx          # Component
3├── Button.styles.ts    # Styles
4├── Button.test.tsx     # Tests
5├── Button.types.ts     # Types
6└── index.ts            # Export

4. Shared vs Feature-specific
   • If something is used in more than 2 places -> shared
   • If something is specific to a feature -> keep it in the feature

Practical tips for project structure

1. Start simple - Don't over-engineer a complex structure at the beginning of a project. For a small application, type-based may suffice; only later refactor to feature-based as the project grows.

2. Refactor when needed - Adapt the structure as the project develops. If a folder has more than 10-15 files, consider splitting it.

3. Keep components small - Components should be small and focused on a single task. If a component has more than 200-300 lines, consider splitting it.

4. Group related files - Keep files that are closely related together. If you always edit two files together, they should probably be in the same folder.

5. Document - Add README.md to main directories to explain their purpose and structure.

6. Consistency above all - Choose one style (feature-based or type-based) and stick to it throughout the project. The worst thing is mixing styles.

Tools that help with code organization

1. ESLint - Helps maintain consistent code style and catch potential errors
2. Prettier - Automatically formats code according to established rules
3. Import sorter - Sorts imports for better readability
4. Path aliases - Simplifies imports using aliases like @components, @utils

1// tsconfig.json or jsconfig.json
2{
3  "compilerOptions": {
4    "baseUrl": "src",
5    "paths": {
6      "@components/*": ["shared/components/*"],
7      "@features/*": ["features/*"],
8      "@utils/*": ["shared/utils/*"],
9      "@hooks/*": ["shared/hooks/*"]
10    }
11  }
12}
13
14// Usage
15import Button from '@components/Button';
16import { useAuth } from '@features/auth';
17import { formatDate } from '@utils/formatDate';

A well-organized project structure greatly facilitates work, especially in large teams and projects. Remember that there is no single "right" structure - the most important thing is that it is consistent, logical for your team, and scalable as the project grows.