React folder structures... a topic that has been around for ages. But still React’s unopinionated approach frequently raises questions: “Where should I put my files? How should I organize my code?” Honestly, even with years of experience, I found myself asking the same questions.
So I went out to get an overview of the most popular approaches to organizing React projects. Based on my research these are:
- grouping by file type (e.g. separate folders for components, contexts, hooks)
- grouping by pages with global folders for contexts, hooks, etc
- grouping by pages with colocation of related components, contexts, and hooks
- grouping by features.
This write-up reflects my observations of these folder structures evolving in a growing codebase and the problems they can cause. It also includes a short list of best practices and a challenge to turn a design from my upcoming course into a feature-based folder structure.
We won't lay out every detail but rather take a big-picture perspective. In other terms: Where we put our App.js file is less important than the overall approach to organizing files.
To juice this story up we’ll follow the (slightly satiric) journey of a new startup through different stages and a growing codebase. The ingenious idea: We’ll build the next todo app!
Table of Contents
- Prototype: Group by file types
- Investment: More files → nesting
- Growth: We need pages
- World Domination: Colocation
- Exit: Group by Features
- Discussion of the feature-driven folder structure
- Best Practices
- Challenge: How would you structure a project based on this design?
Prototype: Group by file types
Obviously, we have a great vision for our startup. Disruption, conquering the world, you know the drill. But everyone has to start small.
So we begin with the React docs. We read that we shouldn’t spend more than 5 minutes deciding on a folder structure. OK, so let’s quickly take inventory:
As the first version of our todo startup, a simple list of todo items would do. That should get us some early pre-seed investment, don't you think?
The simplest folder structure for this case seems to be the “group files by their types” option mentioned in the React docs. This makes our lives easy: Components go in the components folder, hooks in the hooks folder, and contexts in the contexts folder. And since we’re not cavemen we create a folder per component that contains styles, tests, and what not as well.
└── src/
├── components/
│ │ # I'm omitting the files inside most folders for readability
│ ├── button/
│ ├── card/
│ ├── checkbox/
│ ├── footer/
│ ├── header/
│ ├── todo-item/
│ └── todo-list/
│ ├── todo-list.component.js
│ └── todo-list.test.js
├── contexts/
│ │ # no idea what this does but I couldn't leave this folder empty
│ └── todo-list.context.js
└── hooks/
│ # again no idea what this does but I couldn't leave this folder empty
└── use-todo-list.js
This looks pretty simple. And for someone new to programming, this is a great and uncomplicated way to get started. No need to overthink it.
But as you can guess it won't stay this simple for long.
Investment: More files → nesting
Our todo app works great but we’re running out of money. It’s time to get investors on board! Which means we need to show progress. And the best way to show progress is adding new features, right?
Geniuses that we are we have an idea: Why not support editing of todo items? Awesome! We just need a form to edit the todos and maybe a modal to display the form.
└── src/
├── components/
│ ├── button/
│ ├── card/
│ ├── checkbox/
│ │ # this modal shows a form to edit a todo item
│ ├── edit-todo-modal/
│ ├── footer/
│ ├── header/
│ ├── modal/
│ ├── text-field/
│ │ # here is the form that is shown by the modal
│ ├── todo-form/
│ ├── todo-item/
│ │ # the edit modal is shown on top of the todo list
│ └── todo-list/
│ ├── todo-list.component.js
│ └── todo-list.test.js
├── contexts/
│ ├── modal.context.js
│ └── todo-list.context.js
└── hooks/
├── use-modal.js
├── use-todo-form.js
└── use-todo-list.js
Not too bad but the components folder is getting crowded. It’s also slightly annoying that related folders like checkbox and text-field (both form fields) or edit-todo-modal and todo-form (parent and child) are so far apart.
Maybe we could group and colocate components?
└── src/
├── components/
│ ├── edit-todo-modal/
│ │ ├── edit-todo-modal.component.js
│ │ ├── edit-todo-modal.test.js
│ │ │ # colocate -> todo-form is only used by edit-todo-modal
│ │ ├── todo-form.component.js
│ │ └── todo-form.test.js
│ ├── todo-list/
│ │ │ # colocate -> todo-item is only used by todo-list
│ │ ├── todo-item.component.js
│ │ ├── todo-list.component.js
│ │ └── todo-list.test.js
│ │ # group simple ui components in one folder
│ └── ui/
│ ├── button/
│ ├── card/
│ ├── checkbox/
│ ├── footer/
│ ├── header/
│ ├── modal/
│ └── text-field/
├── contexts/
│ ├── modal.context.js
│ └── todo-list.context.js
└── hooks/
├── use-modal.js
├── use-todo-form.js
└── use-todo-list.js
With this folder structure, it’s easier to get an overview of the important functionality. We removed clutter from the components folder in two ways:
- By colocating child components with their parents.
- By grouping the generic UI and layout components in the
uifolder.
The cleaner structure becomes apparent when we collapse the folders:
└── src/
├── components/
│ ├── edit-todo-modal/
│ ├── todo-list/
│ └── ui/
├── contexts/
└── hooks/
Growth: We need pages
Our startup continues to grow. We launched the app to the public and have a handful of users. Of course, they start complaining right away. Most importantly:
Our users want to create their own todo items!
With a bit of thinking, we find a simple solution: we add a second page where users can create todos via a form. Luckily we can reuse the form for editing todos. That’s amazing because it saves precious resources of our developer team.
Anyway, having custom todo items means we need a user entity and authentication. Since the todo form will now be shared between the “create todo page” and the “edit todo modal” we should move it up to the components folder again.
└── src/
├── components/
│ │ # we now have multiple pages
│ ├── create-todo-page/
│ ├── edit-todo-modal/
│ ├── login-page/
│ │ # this is where the todo-list is now shown
│ ├── home-page/
│ ├── signup-page/
│ │ # the form is now shared between create page and edit modal
│ ├── todo-form/
│ ├── todo-list/
│ │ ├── todo-item.component.js
│ │ ├── todo-list.component.js
│ │ └── todo-list.test.js
│ └── ui/
├── contexts/
│ ├── modal.context.js
│ └── todo-list.context.js
└── hooks/
│ # handles the authorization
├── use-auth.js
├── use-modal.js
├── use-todo-form.js
└── use-todo-list.js
What do you think about the folder structure now? I see a few problems.
First, the components folder is getting crowded again. But admittedly, we won’t be able to avoid this in the long run. At least if we want to keep our folder structure somewhat flat. So let's disregard this problem.
Second (and more importantly), the components folder contains a mixture of different kinds of components:
- pages (which are entry points to the app and thus important for new devs to understand the codebase)
- complex components with potential side effects (e.g. the forms)
- and simple UI components like a button.
The solution: We create a separate pages folder. We move all the page components and their children there. Only components that are shown on multiple pages stay in the components folder.
└── src/
├── components/
│ │ # the form is shown on the home and create todo page
│ ├── todo-form/
│ │ # we could also ungroup this folder to make the components folder flat
│ └── ui/
├── contexts/
│ ├── modal.context.js
│ └── todo-list.context.js
├── hooks/
│ ├── use-auth.js
│ ├── use-modal.js
│ ├── use-todo-form.js
│ └── use-todo-list.js
└── pages/
├── create-todo/
├── home/
│ ├── home-page.js
│ │ # colocate -> the edit modal is only used on the home page
│ ├── edit-todo-modal/
│ └── todo-list/
│ ├── todo-item.component.js
│ ├── todo-list.component.js
│ └── todo-list.test.js
├── login/
│ # don't forget the legal stuff :)
├── privacy/
├── signup/
└── terms/
To me, this looks much cleaner. When a new developer joins the company it’s now easy for them to identify all the pages. This gives them an entry point to investigate the codebase or debug the application.
This seems to be a popular folder structure that many developers use. Here are two examples:
- Tania Rascia suggests a similar folder structure and goes into more detail.
- Max Rozen uses a similar folder structure with a few additional guidelines.
But since the goal of our startup is to conquer the world we obviously can't just stop here.
World Domination: Colocation
We’ve grown into a serious business. The world’s most popular todo app (according to it’s 5-star rating). Everyone wants to pour money into our startup. Our team grows and with it our codebase.
└── src/
├── components/
├── contexts/
│ ├── modal.context.js
│ ├── ... # imagine more contexts here
│ └── todo-list.context.js
├── hooks/
│ ├── use-auth.js
│ ├── use-modal.js
│ ├── ... # imagine more hooks here
│ ├── use-todo-form.js
│ └── use-todo-list.js
└── pages/
Sorry, I ran out of creativity. You get the point: The global hooks and contexts folders get crowded.
At the same time, the code for the more complex components is still scattered over multiple folders. The component may live somewhere in the pages folder, using a shared component in the components folder and relying on business logic in the contexts and hooks folders. With a growing codebase, this makes it a lot harder to track down dependencies between files and promotes intertwined code.
Our solution: colocation! Whenever possible we move the contexts and hooks next to the components where they are used.
└── src/
├── components/
│ ├── todo-form/
│ └── ui/
├── hooks/
│ │ # not much left in the global hooks folder
│ └── use-auth.js
└── pages/
├── create-todo/
├── home/
│ ├── home-page.js
│ ├── edit-todo-modal/
│ └── todo-list/
│ ├── todo-item.component.js
│ ├── todo-list.component.js
│ ├── todo-list.context.js
│ ├── todo-list.test.js
│ │ # colocate -> this hook is only used by the todo-list component
│ └── use-todo-list.js
├── login/
├── privacy/
├── signup/
└── terms/
We got rid of the global contexts folder. Unfortunately, there’s no good place to put the use-auth file so the global hooks folder stays for now. No drama, but the fewer global folders the better. They quickly turn into a dumping ground.
The most important advantage of this folder structure: We can grasp all the files that belong to a feature at once. No need to look into 5 different folders to find the code for a single component.
But at the same time, there are still some problems:
- The code related to the “todo” entity is spread over multiple folders. Which will become a bit messy once we start adding more entities.
- Would you guess that the
todo-listcomponent lives in thehomefolder just from looking at the folder structure?
└── src/
├── components/
├── hooks/
└── pages/
├── create-todo/
├── home/
├── login/
├── privacy/
├── signup/
└── terms/
Exit: Group by Features
Our dreams come true: we’re about to sell our startup for billions. We created a unicorn 🦄 FAANGT.
But with success comes responsibility: our users demand new features. Again. Most importantly they want to create different projects to keep their todo items for work separate from the todo items on their grocery list. Who could have guessed...
Our solution: we add a new “project” entity that contains a list of todo items.
We decide to add two new pages. One to create a project and one to show the project including its todos. The home page has to change as well. It should show a list of all projects as well as a list of all todos.
That means the todo-list component is now used on two pages so it has to move to the common components folder
└── src/
├── components/
│ ├── todo-form/
│ │ # is now shared between home and project page
│ ├── todo-list/
│ │ ├── todo-item.component.js
│ │ ├── todo-list.component.js
│ │ ├── todo-list.context.js
│ │ ├── todo-list.test.js
│ │ └── use-todo-list.js
│ └── ui/
└── pages/
├── create-project/
├── create-todo/
│ # shows now a list of projects and an overview of all todos
├── home/
│ ├── index.js
│ ├── edit-todo-modal/
│ └── project-list/
├── login/
├── privacy/
│ # shows a list of todos belonging to a project
├── project/
├── signup/
└── terms/
This still looks quite clean. But I can see two problems:
- Looking at the
pagesfolder it’s not immediately clear that this app has todos, projects, and users. We can understand it but we first need to process folder names likecreate-todo(todo entity) orlogin(user entity) and separate them from the unimportant stuff (e.g. privacy and terms). - It feels arbitrary that some components exist in the shared
componentsfolder just because they are used on multiple pages. You need to know where and in how many places a component is used to understand in which folder you can find it.
At this point you might think: you can simply open a file by its name with the help of your IDE (e.g. by hitting “Ctrl + P” in VS Code). True. But that doesn't help much if you don't remember the name in the first place. So from my perspective, it's always good if you can navigate a codebase in multiple ways.
Let’s adjust the folder structure one last time and group our files by feature.
“Feature” is a pretty broad term and you’re free to choose whatever that means to you. In this case, we go for a combination of entities (todo, project, and user) as well as a ui folder for components like buttons, form fields, and so on.
└── src/
├── features/
│ │ # the todo "feature" contains everything related to todos
│ ├── todos/
│ │ │ # this is used to export the relevant modules aka the public API (more on that in a bit)
│ │ ├── index.js
│ │ ├── create-todo-form/
│ │ ├── edit-todo-modal/
│ │ ├── todo-form/
│ │ └── todo-list/
│ │ │ # the public API of the component (exports the todo-list component and hook)
│ │ ├── index.js
│ │ ├── todo-item.component.js
│ │ ├── todo-list.component.js
│ │ ├── todo-list.context.js
│ │ ├── todo-list.test.js
│ │ └── use-todo-list.js
│ ├── projects/
│ │ ├── index.js
│ │ ├── create-project-form/
│ │ └── project-list/
│ ├── ui/
│ │ ├── index.js
│ │ ├── button/
│ │ ├── card/
│ │ ├── checkbox/
│ │ ├── header/
│ │ ├── footer/
│ │ ├── modal/
│ │ └── text-field/
│ └── users/
│ ├── index.js
│ ├── login/
│ ├── signup/
│ └── use-auth.js
└── pages/
│ # all that's left in the pages folder are simple JS files
│ # each file represents a page (like Next.js)
├── create-project.js
├── create-todo.js
├── index.js
├── login.js
├── privacy.js
├── project.js
├── signup.js
└── terms.js
Note that we introduced index.js files to each folder. These are often referred to as the public API of a module or a component. If you don’t know what that means you can find a more detailed explanation further below.
But first, let’s discuss the new “group by features” folder structure.
Discussion: Feature-Driven Folder Structure and Screaming Architecture
In his article Screaming Architecture Bob Martin says:
Your architectures should tell readers about the system, not about the frameworks you used in your system. If you are building a health-care system, then when new programmers look at the source repository, their first impression should be: “Oh, this is a heath-care system”.
Let’s remember our initial folder structure where we grouped our files by type:
└── src/
├── components/
├── contexts/
└── hooks/
Does this tell us something about the system or the framework? This folder structure screams: “I’m a React app.”
What about our final feature-driven folder structure?
└── src/
├── features/
│ ├── todos/
│ ├── projects/
│ ├── ui/
│ └── users/
└── pages/
├── create-project.js
├── create-todo.js
├── index.js
├── login.js
├── privacy.js
├── project.js
├── signup.js
└── terms.js
We have no idea which framework was used. But this folder structure jumps at you and screams “Hey, I'm a project management tool”.
That’s looks pretty much like what Uncle Bob describes.
Apart from the descriptive architecture, the features and pages give a developer two different entry points to the application.
- If we need to change a component and only know that it’s on the home page open
pages/home.jsand click through the references. - If we need to change the
TodoListbut don’t know where it’s used we simply open thefeatures/todofolder and we’ll find it somewhere inside.
And finally, we got rid of the global contexts and hooks folders. We can still re-introduce them if necessary. But at least for the moment, we removed these potential dumping grounds.
I personally am very happy with this folder structure. We could continue for a bit and clean up the folder structure within a feature. For example, the todo folder currently looks a bit messy. Alan Alickovic with his awesome example project Bulletproof React suggests separating the files inside each feature by file type (as we did in the beginning).
But from my perspective, our current folder structure is sufficiently clean and descriptive. Due to the self-contained nature of the “features” it should be easy to refactor if necessary. At the same time, our folder structure is simple enough to use in a project from the start. It may save us some headaches in the long run.
From my experience, many projects evolve in a similar way as described on this page. But due to time pressure, the developers never have the chance to clean up the folder structure. So the project ends up in a mess of different approaches. Starting with a feature-driven folder structure can help keeping the app clean over the long run.
If you'd like to take a deep dive into the feature-driven folder structure here is a list of more resources:
- The source code of Bulletproof React and its docs about the folder structure.
- A tweet by Swyx.
- A great blog post by Kolby Sisk that goes into more detail.
- A blog post by Robin Wieruch that inspired this article (even though Robin seems to prefer to group files by type).
- Feature Sliced - an architectural methodology for frontend projects (unfortunately with an incomplete English version).
Best practices
Absolute imports
Let's say we want to render a button in the todo list component inside the file features/todo/todo-list. By default we would use a relative import:
import { Button } from "../../ui/button";
...
Managing the relative paths with ../.. can become annoying especially during refactoring sessions when you move files around. It also quickly turns into guesswork to figure out how many .. are required.
As an alternative, we can use absolute imports.
import { Button } from "@features/ui/button";
...
Now it doesn't matter where you move the TodoList component. The import path will always be the same.
With Create React App absolute imports are very easy to set up. You just add a jsconfig.json file (or tsconfig.json for TypeScript) and define the paths aliases:
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@features/*": ["src/features/*"],
}
}
}
You can find more detailed walkthroughs here for React and here for Next.js.
index.js as public API
In our final folder structure, we added an index.js to each feature and component folder. Here a quick reminder:
└── src/
├── features/
│ ├── todos/
│ │ │ # this is used to export the relevant modules aka the public API
│ │ ├── index.js
│ │ ├── create-todo-form/
│ │ ├── edit-todo-modal/
│ │ ├── todo-form/
│ │ └── todo-list/
│ │ │ # the public API of the component (exports the todo-list component and hook)
│ │ ├── index.js
│ │ ├── todo-item.component.js
│ │ ├── todo-list.component.js
│ │ ├── todo-list.context.js
│ │ ├── todo-list.test.js
│ │ └── use-todo-list.js
│ ├── projects/
│ ├── ui/
│ └── users/
└── pages/
As mentioned, these index.js files are often referred to as the public API of a module or a component.
But what does that mean?
Here is an example of how the index file in the folder features/todo/todo-list might look like:
import { TodoList } from "./todo-list.component";
import { useTodoList } from "./use-todo-list";
export { TodoList, useTodoList };
The file simply imports and exports some modules. Here is an even shorter version:
export { TodoList } from "./todo-list.component";
export { useTodoList } from "./use-todo-list";
And the file feature/todo/index.js just exports everything from its subfolders.
export * from "./create-todo-form";
export * from "./todo-list";
// ... and so on
How does that help us?
Imagine you want to render the TodoList component inside the file pages/home. Instead of importing from the nested folder like this
import { TodoList } from "@features/todo/todo-list/todo-list.component";
...
we can simply import from the todo feature directly.
import { TodoList } from "@features/todo";
...
This has a few benefits:
- It looks nicer.
- A developer doesn't need to know the inner folder structure of a feature to use one of its components.
- You can define which components etc. you want to expose to the outside. Only the things you export in your index files should be used in other parts of the app. The rest is internal/private. Hence the name “public API”.
- You can move around, rename, or refactor everything inside a feature folder as long as the public API stays the same.
kebab-case for file and folder names
Like many others, I used to name component files with PascalCase (e.g. MyComponent.js) and functions/hooks with camelCase (e.g. useMyHook.js).
Until I switched to a MacBook.
During a refactoring session, I renamed a component file called myComponent.js to the correct format MyComponent.js. Everything worked locally but for some reason, the CI on GitHub started complaining. It claimed that the import statement below was broken.
import MyComponent from "./MyComponent";
Turns out, MacOS is a case-insensitive file system by default. MyComponent.js and myComponent.js are the same thing. So Git never picked up the change in file name. Unfortunately, the CI on GitHub used a Linux image. And this one is case-sensitive. So according to my CI the file didn’t exist while my local machine said everything was OK.
It took me hours to understand this. And apparently, I'm not the only one who ran into this problem:
The solution: use kebab-case for your file and folder names. For example:
- Instead of
MyComponent.jswritemy-component.js. - Instead of
useMyHook.jswriteuse-my-hook.js.
This is what Next.js uses by default. Angular included it in its coding styleguide. I don't see a reason why not to use kebab-case but it might save you or a teammate of yours some headaches.
Challenge: How would you structure a project based on this design?
This is a design of an error logging tool for web apps (e.g. like Sentry) from my upcoming course.
- The entity at the foundation of this app is an “organization”.
- Each organization has projects and users assigned to it.
- Each project has issues (e.g. errors that are sent from an organization’s website).
- Each of the top items in the left navigation represents a page.
How would you turn this design into a feature-based folder structure? (You can find my solution below. Don’t peak.)
...
...
...
...
...
...
└── src/
├── features/
│ ├── alerts/
│ ├── issues/
│ │ # this contains the settings
│ ├── organization/
│ ├── projects/
│ │ ├── index.js
│ │ ├── project-card.js
│ │ └── project-list.js
│ ├── ui/
│ │ ├── index.js
│ │ ├── card/
│ │ ├── header/
│ │ ├── footer/
│ │ ├── side-navigation/
│ │ └── tag/
│ └── users/
└── pages/
├── alerts.js
├── issues.js
├── projects.js
├── settings.js
└── users.js
Top comments (21)
I found your article fantastic. Really very good. 👏👏👏
One thing I always see and today was the 1st time I asked myself.
how is this folder structure made? Is it a plugin or do you make the folder structure manually?
Thanks a lot for the nice words. I would create the folder structure manually. And I think most people would. It's only a one-time effort in the end. But there was a thread on Reddit yesterday where nx.dev was suggested to create a project. But honestly, I have never used it and also don't know what exact folder structure it creates.
Excellent article
Really good
This is great! Thanks for this!
Awesome Article 👍
Great article
Good walkthrough and great tips!
Thanks for the feedback
I'm always scared of nested folders mess..
Not sure if you have taken a look at Unreal engine source code but It is nested asf and finding something relevant blows away your mind
Yeah, I definitely wouldn't recommend nesting too deeply. Especially not components within components within components. That gets really messy.
Really good post. Bookmarked!
wonderful. Great article. It help me a lot. I was needing this
Great article. Nice tips :D
Great article man , thank you for sharing.
Do you think there should be a common folder for hooks that you may need to use across your features?
You can use one for sure. But I'd wait with creating global folders for common stuff until they're really necessary.
Hi @jkettmann! Just wanted to give a huge shoutout for your awesome article 👏. Big thanks for sharing! I came across this article a few months ago and it opened my eyes on screaming architecture. It also inspired me to create my own implementation of it with a complete project setup that can be use by anyone for their next or existing project. It's now live on GitHub: github.com/shaquille-galanto/screa.... Check it out if you have a moment. Thank you 🙌
I used to do something similar to this but now I just have /pages (because of next js I have to) and /components and /hooks ect are completely flat.
Each component will be a folder containing a single file of code, a styles file and potentially a test file. It's always a folder even if it has a single file so it's alway in alphabetical order it doesn't list the folders and then the single files in the IDE.
The moment you start having file hierarchies you start needing knowledge of the app to traverse it to find stuff. Also if you have a reusable component the you start having a "shared" location so now a file could be in shared or somewhere in the hierarchy or duplicated. If you keep it flat it's going to be huge but if you have a complicated app your going to have loads of features anyway.
When you try to find stuff you start with the page/route and you work your way in and you can see the list of components the whole time.
I found this blog post extremely insightful & useful! Thank You very much, Johannes!