Organizing files and directories within a React project is crucial for maintainability, scalability, and ease of navigation. This article explores the general architecture and folder structures across different scales of React projects, providing clear demonstrations for each level.
1️⃣ Level 1: Grouping by "File Types"
This structure is characterized by its simplicity - grouping files by their type:
└── src/ ├── assets/ ├── api/ ├── configs/ ├── components/ │ ├── SignUpForm.tsx │ ├── Employees.tsx │ ├── PaymentForm.tsx │ └── Button.tsx ├── hooks/ │ ├── usePayment.ts │ ├── useUpdateEmployee.ts │ ├── useEmployees.ts │ └── useAuth.tsx ├── lib/ ├── services/ ├── states/ └── utils/
- Project Size: Small to Medium
- Advantages: Simple & straightforward
- Disadvantages:
- Will inflate quickly and become hard to maintain
- No separation of business concerns
Let's say you have a lot of code revolving around payment. One day the whole business changes or is no longer needed, how easy is it to replace or remove it? With this folder structure, you'll have to go through every folder and the files inside it to make the necessary changes. And if the project keeps growing larger, it'll soon grow into a maintenance hell that will only get worse over time.
2️⃣ Level 2: Grouping by "File Types" and Features
As projects grow, the "Level 2" structure introduces grouping by feature within each type:
└── src/ ├── assets/ ├── api/ ├── configs/ ├── components/ │ ├── auth/ │ │ └── SignUpForm.tsx │ ├── payment/ │ │ └── PaymentForm.tsx │ ├── common/ │ │ └── Button.tsx │ └── employees/ │ ├── EmployeeList.tsx │ └── EmployeeSummary.tsx ├── hooks/ │ ├── auth/ │ │ └── useAuth.ts │ ├── payment/ │ │ └── usePayment.ts │ └── employees/ │ ├── useEmployees.ts │ └── useUpdateEmployee.ts ├── lib/ ├── services/ ├── states/ └── utils/
- Project Size: Medium to Large
- Advantages:
- Simple & straightforward
- Stuff are grouped by features
- Disadvantages:
- Logic related to a feature is still spread across multiple folder types
Now let's come back to the problem statement where the payment module needs to be modified or removed. With this structure, it's a lot easier to do that now.
The "Level 2" folder structure is the one that I'd recommend if you don't know what to choose.
3️⃣ Level 3: Grouping by Features/Modules
For larger projects, the "Level 3" structure offers a highly modular approach, defining clear boundaries for different aspects of the application within each module:
└── src/ ├── assets/ ├── modules/ | ├── core/ │ │ ├── components/ │ │ ├── design-system/ │ │ │ └── Button.tsx │ │ ├── hooks/ │ │ ├── lib/ │ │ └── utils/ │ ├── payment/ │ │ ├── components/ │ │ │ └── PaymentForm.tsx │ │ ├── hooks/ │ │ │ └── usePayment.ts │ │ ├── lib/ │ │ ├── services/ │ │ ├── states/ │ │ └── utils/ │ ├── auth/ │ │ ├── components/ │ │ │ └── SignUpForm.tsx │ │ ├── hooks/ │ │ │ └── useAuth.ts │ │ ├── lib/ │ │ ├── services/ │ │ ├── states/ │ │ └── utils/ │ └── employees/ │ ├── components/ │ │ ├── EmployeeList.tsx │ │ └── EmployeeSummary.tsx │ ├── hooks/ │ │ ├── useEmployees.ts │ │ └── useUpdateEmployee.ts │ ├── services/ │ ├── states/ │ └── utils/ └── ...
- Project Size: Large and Complex
- Advantages:
- Stuff are clearly grouped by features/modules
- Features/Modules are clear representations of objects in the real world
- Disadvantages:
- You'll have to be well-aware of the business logic to make the right grouping decisions
With this, if you are to remove or modify the payment logic, you'll know right away where to start.
Give Consistent Meanings to Folder Names
Regardless of the structure level, certain folder names should carry specific meanings. What a folder name means may vary based on your preferences or the project's conventions.
Here's what I usually think about folder names:
UI Components
- components: React components - the main UI building blocks.
- design-system: Fundamental UI elements and patterns based on the design system.
- icons: SVG icons that are meant to be used inline.
React Specific
- hooks: Custom React hooks for shared logic.
- hocs: React Higher-order Components.
- contexts/providers: Contains React Contexts and Providers.
Utilities & External Integrations
- utils: Utilities for universal logic that is not related to business logic or any technologies, e.g. string manipulations, mathematic calculations, etc.
- lib: Utilities that are related to certain technologies, e.g. DOM manipulations, HTML-related logic, localStorage, IndexedDB, etc.
- plugins: Third-party plugins (e.g. i18n, Sentry, etc.)
Business Logic
- services: Encapsulates main business & application logic.
- helpers: Provides business-specific utilities.
Styles
- styles: Contains (global) CSS or CSS-in-JS styles.
TypeScript and Configurations
- types: For general TypeScript types, enums and interfaces.
- configs: Configs for the application (e.g. environment variables)
- constants: Constant, unchanged values (e.g.
export const MINUTES_PER_HOUR = 60
).
Server Communication
- api: For logic that communicates with the server(s).
- graphql: GraphQL-specific code.
State Management
- states/store: Global state management logic (Zustand, Valtio, Jotai, etc.)
- reducers, store, actions, selectors: Redux-specific logic
Routing
- routes/router: Defining routes (if you're using React Router or the like).
- pages: Defining entry-point components for pages.
Testing
- tests: Unit tests and other kinds of tests for your code.
🏁 Conclusion
Choosing the right folder structure in React projects is essential and should be based on the project's size and complexity. While "Level 1" may suffice for small projects, "Level 2" and "Level 3" offer more organized and modular structures for medium and large projects. Personally, I'd often recommend the "Level 2" folder structure. Also, Understanding common folder names helps maintain a consistent and intuitive architecture across React applications.
In case you think it was a good read, you'll probably find this useful as well:
⚛️ Demystifying React's Types: Component types
Will T. ・ Mar 28
#typescript #react #webdev #frontend
If you're interested in Frontend Development and Web Development in general, follow me and check out my articles in the profile below.
Top comments (53)
Subscribe
Just a passionate Software Engineer writing articles on computer science & software development, architecture, and testing 🧪⚙️👨💻 occasionally found watching videos of cats 🐈
-
Location
my IDE
-
Education
Computer Science @ IUBH
-
Work
Full Stack Software Engineer
-
Joined
I don't think the statement you wrote on the disadvantages of level 3
is that much of a disadvantage, because any developer who is already working in the project, and also newcomers would still have a better idea of where to look for things if they are in their respective places, which come with a proper folder structure, in my point of view, and the business logic is thus properly defined. I do find it to be the way to go for big projects, though. Really great naming for the different parts of a React project!👍
I'm a Frontend enthusiast who is specialized in ⚛️. I love sharing my knowledge and experience within my area of expertise.
-
Location
🇻🇳 Vietnam
-
Education
Hanoi University of Science and Technology
-
Work
Frontend Development
-
Joined
Yeah, I had to come up with at least a disadvantage anyway, so... Having clear business concerns takes a bit more mental effort initially, but is not a real disadvantage.
Just a passionate Software Engineer writing articles on computer science & software development, architecture, and testing 🧪⚙️👨💻 occasionally found watching videos of cats 🐈
-
Location
my IDE
-
Education
Computer Science @ IUBH
-
Work
Full Stack Software Engineer
-
Joined
Yes, that could be, especially if you’re a new dev in the team, that can be a great challenge at first, but once you know where to look for things by business concern, it will be easier to find the individual piece of code you are looking for. Good article in general! 👍 but found it funny when you said you had to come up with at least one 😄 sometimes there are things which we really want to find a disadvantage, but we get disappointed 😅
I'm a Frontend enthusiast who is specialized in ⚛️. I love sharing my knowledge and experience within my area of expertise.
-
Location
🇻🇳 Vietnam
-
Education
Hanoi University of Science and Technology
-
Work
Frontend Development
-
Joined
I figured it might be arrogant to say something that I came up with to have no drawbacks whatsoever 🤣.
I use a folder called /pages to signify top level routes, similar to the modules folder. IMO modules is too generic.
I'm a Frontend enthusiast who is specialized in ⚛️. I love sharing my knowledge and experience within my area of expertise.
-
Location
🇻🇳 Vietnam
-
Education
Hanoi University of Science and Technology
-
Work
Frontend Development
-
Joined
Sometimes I also use /pages or /features instead of /modules.
-
Joined
These examples are very "Redux" focused and outdated. No one creates folders like actions
or reducers
anymore. All new projects are trying to stay away from Redux and adopted other state management solutions like "Zustand". Which simplified not just state management but made folder naming more sensible.
I'm a Frontend enthusiast who is specialized in ⚛️. I love sharing my knowledge and experience within my area of expertise.
-
Location
🇻🇳 Vietnam
-
Education
Hanoi University of Science and Technology
-
Work
Frontend Development
-
Joined
I agree that no one really uses Redux if it's a newer project anymore. I also use Zustand/Valtio and React Query in my projects, and I think Redux is redundant and should be discouraged. Nevertheless, it's my/our opinion since a lot of projects out there are still using Redux and some people still find it useful.
My bad for not noticing that those folders appear too often in the examples. Thanks for pointing out the details.
Software Developer and FLOSS Advocate
-
Location
DRCongo, Kisangani
-
Work
Software Developer
-
Joined
Thank you for sharing.
I'd suggest giving a brief intro for different directories, unless it's so obvious. You can see the Gatsby Project Structure.
I'm a Frontend enthusiast who is specialized in ⚛️. I love sharing my knowledge and experience within my area of expertise.
-
Location
🇻🇳 Vietnam
-
Education
Hanoi University of Science and Technology
-
Work
Frontend Development
-
Joined
Thanks. That’d be a nice idea for the next articles.
I'm a Frontend enthusiast who is specialized in ⚛️. I love sharing my knowledge and experience within my area of expertise.
-
Location
🇻🇳 Vietnam
-
Education
Hanoi University of Science and Technology
-
Work
Frontend Development
-
Joined
I used to work on projects that have a parallel __tests/ folder that mimics the same folder structure. I think that's also a good way to organize tests.
For any real projects (not hobby ones) - Level 3 is the only way.
Every other way will be a mess starting starting with 30-100k lines of code.
You may just skip the "modules/" folder entirely and make it more flat.
You always want files with in the same bounded context (term from DDD - Domain Driven Design) to be near each other. Grouping files/folders by domain first is always better than the technical separation.
I'm a Frontend enthusiast who is specialized in ⚛️. I love sharing my knowledge and experience within my area of expertise.
-
Location
🇻🇳 Vietnam
-
Education
Hanoi University of Science and Technology
-
Work
Frontend Development
-
Joined
The "Level 3" folder structure is heavily inspired by DDD. FYI, I actually took the idea from DDD.
Enthusiastic learner • Computer scientist • Python developer • Software business analyst • Unix-like system user
-
Location
Brazil
-
Education
Computer Science at UFSC, Brazil
-
Pronouns
He/Him
-
Work
Enthusiastic learner
-
Joined
For level 3 forward, I'd also consider split each module in its own package, maybe through a monorepo approach; Even because a micro front-end solution could soon help into increase organization for a project that is rapidly growing in complexity
I'm a Frontend enthusiast who is specialized in ⚛️. I love sharing my knowledge and experience within my area of expertise.
-
Location
🇻🇳 Vietnam
-
Education
Hanoi University of Science and Technology
-
Work
Frontend Development
-
Joined
That is also a very reasonable approach, maybe we can even call that "Level 4".
Nice post
I usually use
/components ( all the generic one)
/pages ( contain specific component, Page hooks, Styles)
/config
/lib ( contain generic hooks, rtk, all the logic stuff that Is not a component)
I'm a Frontend enthusiast who is specialized in ⚛️. I love sharing my knowledge and experience within my area of expertise.
-
Location
🇻🇳 Vietnam
-
Education
Hanoi University of Science and Technology
-
Work
Frontend Development
-
Joined
That's similar to the "Level 1" folder structure that I mentioned, right?
I build web apps with React, explaining concepts and code logic to help you understand React better.
-
Location
Uyo, Nigeria
-
Education
University of Uyo
-
Joined
This is one of the best, if not the best article I have seen so far in my search for React Project structures, thank you for sharing. I think it helps to start projects from level 1 and walk your way up to level 3 or so, at least that's what I will do, cause then you can better see what works for you, and what doesn't, and even implement your own style
I'm a Frontend enthusiast who is specialized in ⚛️. I love sharing my knowledge and experience within my area of expertise.
-
Location
🇻🇳 Vietnam
-
Education
Hanoi University of Science and Technology
-
Work
Frontend Development
-
Joined
Yeah, the important thing is consistency, no matter what you choose to go with.
Once you work on a big project, the level 3 type grows on you and it's kind of the type you use even on small projects from that moment on. Because once it becomes natural to you, you use it everywhere, small to large.
I'm a Frontend enthusiast who is specialized in ⚛️. I love sharing my knowledge and experience within my area of expertise.
-
Location
🇻🇳 Vietnam
-
Education
Hanoi University of Science and Technology
-
Work
Frontend Development
-
Joined
And it's also gonna be the only thing that makes sense. Once it gets natural to you, It doesn't even take much mental effort anymore.
As someone who is OCDAF … I truly appreciate this post because when I started I could not find anything about how to structure my projects! I ended up just going back and forth and then projects got too big and it drove me mad!
I'm a Frontend enthusiast who is specialized in ⚛️. I love sharing my knowledge and experience within my area of expertise.
-
Location
🇻🇳 Vietnam
-
Education
Hanoi University of Science and Technology
-
Work
Frontend Development
-
Joined
Oh, an OCD fellow :)). I also feel irritated when I encounter a problem again and again, so I often spend a lot of time trying to solve it once and for all.
I'm Full Stack Developer, Electrical Engineer and Perfectionist.
-
Location
Shanghai
-
Work
Full Stack Developer
-
Joined
Can you clarify the differences between services and helpers for business logic?
I'm a Frontend enthusiast who is specialized in ⚛️. I love sharing my knowledge and experience within my area of expertise.
-
Location
🇻🇳 Vietnam
-
Education
Hanoi University of Science and Technology
-
Work
Frontend Development
-
Joined
Hi, thanks for the question.
- The /services folder mainly contains more complex logic, and it'll most likely use the logic from the /helpers folder. Let's say you want to implement the employee search functionality in the FE side. There can be a lot of fields, and the fields can have different matching logic, and some fuzzy search might also be required. That can be considered complex logic already, and it should live in /services.
- The /helpers folder is mainly for very simple, mainly one-liner logic, e.g.
export const isAdmin = (user: User) => user.role === UserRole.ADMIN;
If you don't want to have the /helpers folder, it's fine to have all the logic live in the /services folder as well.
When I think of the /services folder, it does not only contain pure business logic but can also act like an orchestrator. Meaning it can call functions from the Persistence layer (e.g. network requests from the /api folder, or interacting with localStorage
in the /lib folder, etc.) to get the inputs needed. The /services folder is like a facade (in the Facade design pattern], which I'll talk about more in one of my upcoming articles. Please look forward to it.
I'm Full Stack Developer, Electrical Engineer and Perfectionist.
-
Location
Shanghai
-
Work
Full Stack Developer
-
Joined
martinfowler.com/eaaCatalog/servic... explains the service layer clearly.
Frontend developer || Technical Writing || Web3 Developer. Working to become a proficient Software Engineer
-
Email
-
Location
Kwara State, Nigeria
-
Pronouns
He/Him
-
Work
Software Frontend Developer
-
Joined
Nice write-up, i mean I really love this and i guess I will go for Level 3 when it comes to big project in React
I'm a Frontend enthusiast who is specialized in ⚛️. I love sharing my knowledge and experience within my area of expertise.
-
Location
🇻🇳 Vietnam
-
Education
Hanoi University of Science and Technology
-
Work
Frontend Development
-
Joined
I suggest you try it once and you'll find it beneficial and comfortable to work with.
10+ year client support roles, and currently in technical apprentice program (Bootcamp started Feb 2024)
-
Joined
Super helpful @itswillt. As a beginner in React- we are are just learning on Day 4 out of 5 on the React topic in bootcamp, it is helpful to see the approach on structuring the folders- and your visual examples provide a nice touch! ❤️
I'm a Frontend enthusiast who is specialized in ⚛️. I love sharing my knowledge and experience within my area of expertise.
-
Location
🇻🇳 Vietnam
-
Education
Hanoi University of Science and Technology
-
Work
Frontend Development
-
Joined
Thanks! It's so cool to hear that the article is helpful to your learning process.
Some comments may only be visible to logged-in visitors. Sign in to view all comments.
For further actions, you may consider blocking this person and/or reporting abuse