How to Structure a React App Like a Pro 🔥

So, you’ve started building your React app, and everything is going great, until you realize your project folder is a mess. Sound familiar? Don’t worry, we’ve all been there. Structuring a React app can feel overwhelming, but with the right approach, you can keep your codebase clean, scalable, and easy to navigate.

In this article, I’ll walk you through a folder structure that’s worked wonders for me. It’s beginner-friendly, scalable, and perfect for small to medium-sized projects. Let’s dive in!

1. assets/ 🖼️

This folder is for all your static files like images, icons, fonts, and other media. Keeping them in one place makes it easy to manage and reference them throughout your app.

What to store here:

• Images (logo.png, background.jpg)
• Icons (SVGs or icon fonts)
• Fonts (custom or third-party)

Assets folder

2. components/ 🧩

This is where your reusable UI components live. Think of buttons, cards, modals, and anything else that can be reused across your app.

What to store here:

• Reusable components (Button.jsx, Card.jsx)
• Component-specific styles (if not using CSS-in-JS)
• Subfolders for complex components (e.g., components/Header/)

Components folder

3. contexts/ 🌐

React Context is perfect for managing global state without prop drilling. This folder stores all your context providers and related logic.

What to store here:

• Context providers (AuthContext.js, ThemeContext.js)
• Reducers or custom hooks for context logic

Contexts folder

4. helpers/ 🛠️

This folder is for utility functions that don’t belong to a specific component or feature. These are the little helpers that make your life easier.

What to store here:

• Utility functions (formatDate.js, validateEmail.js)
• Constants (appConstants.js)
• Custom error handlers

Helpers folder

5. hooks/ 🎣

Custom hooks are a game-changer in React. This folder is for all your reusable hooks, keeping them organized and easy to import.

What to store here:

• Custom hooks (useFetch.js, useLocalStorage.js)
• Hooks for specific logic (e.g., useAuth.js, useTheme.js)

Hooks folder

6. layouts/ 🖼️

Layouts are the skeleton of your app. They define the structure of your pages (e.g., header, footer, sidebar) and help maintain consistency across your app.

What to store here:

• Layout components (MainLayout.js, AuthLayout.js)
• Layout-specific styles

Layouts folder

7. pages/ 📄

This folder contains the top-level components that represent each page of your app. Each file here corresponds to a route in your app.

What to store here:

• Page components (Home.jsx, About.jsx, Contact.jsx)
• Page-specific logic and styles

Pages folder

8. services/ 🌍

This folder is for all your API calls and external service integrations. Keeping them separate makes it easy to manage and mock during testing.

What to store here:

• API service files (authService.js, userService.js)
• Configuration files for APIs (e.g., apiConfig.js)

Services folder

9. styles/ 🎨

This folder is for global styles, themes, and CSS utilities. If you’re using a CSS-in-JS library, you might not need this folder, but it’s still useful for global styles.

What to store here:

• Global styles (global.css)
• Theme files (theme.js for styled-components or Material-UI)
• CSS utility classes

Styles folder

10. App.js 🎯

This is the entry point of your app. It’s where you define your routes, wrap your app with providers, and set up any global configurations.

What to include here:

• Routing logic (using react-router-dom)
• Context providers (AuthProvider, ThemeProvider)
• Global error boundaries or wrappers

🗂️ The Full Folder Structure

Here’s the complete folder structure, including the files inside each folder:

The full folder structure

🚀 Why This Structure Works

• Scalability: As your app grows, you can easily add new folders or subfolders without breaking the existing structure.
• Readability: Everything has its place, making it easy for you (or your team) to find what you need.
• Reusability: By separating concerns, you can reuse components, hooks, and utilities across your app.

🛠️ Pro Tips for Structuring Your React App

1. Keep it simple: Don’t overcomplicate the structure. Start with what you need and expand as your app grows.
2. Use meaningful names: Name your files and folders in a way that makes their purpose clear.
3. Document your structure: Add a README.md file to explain your folder structure to your team (or your future self).

🎉 Ready to Build?

Now that you have a solid structure in place, it’s time to start building! Remember, the best structure is the one that works for you and your team. Feel free to tweak this setup to fit your needs.

Happy coding 💻

Thanks for reading! 🙏🏻 I hope you found this useful ✅ Please react and follow for more 😍 Made with 💙 by Hadil Ben Abdallah

Hadil Ben AbdallahFollow

Software Engineer • Technical Content Writer

Comments

[Alex]

Terrible advice, to implement 1 more or less complex page will need 10 files in different directories. Will be a mess that hard to navigate.

Working with codebase structured by many folders, that person also used Crypto.randomUUID() as React key, just because Eslint complained about indexes.
Code should reflect app and business logic, and adapt to it, there is no "right" universal answer.

Just structure folders by routes, put files right there, is something reused, then move it to a folder at the top level

App
-- public (or 'static')
-- routes/pages
-- -- route1
-- -- -- Page.tsx
-- -- -- Component1.tsx
-- -- -- Component2
-- -- -- -- Component2.tsx
-- -- -- -- index.ts
-- -- -- -- index.module.css
-- -- -- -- Component2.test.tsx
-- -- -- index.module.css
-- hooks
-- components
...

Don't do stuff like in picture.

[erkn]

I half agree, clearly context of the content is aiming for mid/big projects. On the other hand projects are alive as long as there are users, so you need to keep adapting your project, making big assumptions will be harder to fix.

[Alex]

There are more important principle than Solid - YAGNI (You aren't gonna need it).

Do things as needed, don't overcomplicate things. Assuming some folder structure from the start is a waste of time.
If project is small, anything will work, if it will grow, most of it will be restructured on the way. So why bother with making 100500 folders.

[Naval Deep]

Its all written by AI

[Ansell Maximilian]

Nice!

[Hadil Ben Abdallah]

Thank you 💙

[Rense Bakker]

Please don't structure your React project like this if a team is going to work on it, seperate the project into modules or use a folder structure that represents the routes of the app. Keep related things together, so other developers can easily find stuff, instead of having to look through several different folders when debugging.

[Hadil Ben Abdallah]

Thank you for sharing your perspective!

You’re absolutely right, when working in a team, modularity and route-based organization can make a huge difference in maintainability and collaboration.

The structure I shared is more of a general starting point for small to medium-sized projects, especially for solo developers or beginners. However, for larger teams or complex apps, organizing by modules or routes is often the better approach. It keeps related files (components, styles, hooks, etc.) together, making it easier for everyone to navigate and debug.

For example, a route-based structure might look like this:

src/  
├── features/  
│   ├── auth/  
│   │   ├── components/  
│   │   ├── hooks/  
│   │   ├── services/  
│   │   └── index.js  
│   ├── dashboard/  
│   │   ├── components/  
│   │   ├── hooks/  
│   │   ├── services/  
│   │   └── index.js  
└── shared/  
    ├── components/  
    ├── hooks/  
    └── utils/  

This way, everything related to a specific feature or route is grouped together, which can be a game-changer for team collaboration.

Ultimately, the best structure depends on the size of the project, the team’s preferences, and the complexity of the app. The key is to keep it organized, consistent, and easy to navigate.

Thanks again for your comment

[Tomas Stveracek]

Great article! I really like how you explained the structure of a React app. It's clear and easy to follow, especially for beginners. I'll definitely use some of these tips in my own projects. Thanks for sharing!

[Hadil Ben Abdallah]

You’re welcome! I’m glad you found it helpful 💙

[Vaibhav thakur]

Great insights! The structured approach you’ve outlined for building React apps will definitely help developers keep their projects organized and maintainable. The clear explanation of the folder structure and separation of concerns is particularly helpful for scaling applications. Thanks for sharing these valuable tips

[Hadil Ben Abdallah]

You’re welcome! I’m glad you found it helpful 💙

[Block Experts]

Using Javascript instead of Typescript is bad idea! ;)

[JACK NGUYEN]

wow

[Hadil Ben Abdallah]

🤗😍

[Sateesh]

Good one

[Hadil Ben Abdallah]

Thank you 💙

[Shaquille Niekerk]

Great read!

[Hadil Ben Abdallah]

Thank you 💙

[Kunal Kumar]

Nice

[Hadil Ben Abdallah]

Thank you 💙