Is there a perfect file structure for React projects? Probably not. But some are far better than others.
Over the years I discovered that I tend to structure files in some specific ways, which I believe are easier to understand and reasonable.
Meaningful folder names
Naming things is one of the toughest things to get right in programming. One of my favorite tactics to naming folders is to extract the subject and use it:
- want a place for public resources? the
publicfolder should be a good fit; - have some custom hooks that you are proud of? keep them easy to find in the
hooksfolder; - want to include yet another css file? store them in the
cssfolder.
And so on and so forth.
Little to no folder nesting
I always wondered about the src folder and why it exists. And to this day it still is one of the many mysteries of programming.
I like to keep all my folders as close to the project root as possible. This way, they can be discovered more easily by any new dev working on the project.
Avoiding too much nesting is also recommended by the official React documentation as well.
Grouping by feature
The components folder is one of my exceptions: it has two (2) levels of nesting. Common components are accessible right from the folder root, while "specialized" components have they own folder.
The contents of the components folder:
-
Button.jsx- common button components -
Link.jsx- common link component -
Forms-
AddClientForm.jsx- specific "form" component -
EditClientForm.jsx- another specific "form" component
-
Minimal example
This is the project structure for a starter project I authored and for many projects I'm working on right now.
apicomponentscssdatafunctionshooksmodelspagespublicLICENSEREADME.md
I hope the folder structure is self explanatory. If it is not, I have done a lousy job at naming folders. Let me know in the comment section below.
Closing thoughts
My favorite file structure:
- is easy to read and understand
- is shallow nested
- is grouped by features
Have a different opinion? Can't wait to hear it!
Top comments (26)
I believe foldering by context (I.e home page, profile page, etc.) instead of foldering by role (components, hooks, etc.) is a much more convinient way to structure your folders, because when another developer looks at your src folder they know exactly what the project is made for.
However, I use foldering by role on pretty much anything else because a function or a hook is more generic, it does not have to depend on some context.
Another benefit of foldering by role. Whenever I want to update something related to a hook, I always know where to go: somewhere in the hooks folder
Personally, the vast majority of the hooks I write are written because I wanted to extract some logic from the UI component using it, and for that reason I place in in the same folder as the component.
For hooks used in multiple places, I usually create a
helpersfolder.In a project where you have hooks that don't fall in neither of these two categories, foldering by role would be indeed the best choice. But I can't think of many examples that don't fall in one of these categories.
I choose foldering by context only on my React components, which are composable by their nature. I do this whenever I can extract a prefix or a suffix from the filename (see AddClientForm.jsx in the folder Forms)
That's really cool
I believe flat folder structures do fine for small to intermediate project sizes.
But nested folder structures are unavoidable for large projects that contain a lot of components.
Sure, it makes sense to expand and nest some folders when the project grows in size. But I have seen some small projects with many levels of unnecesary nesting.
From what point onward would you consider a project large?
I agree many projects have very complicated folder nesting without clear purpose.
I would consider a React project in particular already large when you have > 40 components. But that's highly subjective. That's the threshold around which I would consider a nested folder structure.
But the nested folder structure must not be implemented everywhere. Some projects have a lot of components but not so many pages or services...
I guess keeping it practical is the best advice you can give someone here.
Keeping it practical and starting simple is great advice!
Hello, I just want to add a quick note to the meaning of the
srcfolder. From my personal point of view, I always liked the idea of separating source code from the rest of the repository.I like to keep in my root basic configuration files (linters, editor config and so on),
docs,srcor the module folder (I am a Python developer). I think repository is then much more cleaner because you don't have source code mixed with files and folders like.githuband other stuff that comes in the way during the project.Hello Jakub! I see many devs in the comment section prefer the src folder as well. Is this a standard in python or just a preference?
Hi Victor, I don't want to say that it's some kind of standard. There is no such thing as a standardized project structure (not even in Python PEPs). As I said in the previous comment, the project repository is not only a source code but lots of accompanying files such as configs and documentation. The
srcfolder is not just a Python thing but it's very common in many other languages such as C++ or Java. It comes from the necessity to separate source code from the rest of the project files in larger projects. Here are a few examples of popular projects that come to my mind:Also, there is a lot of popular projects which are not using such a structure.
To sum up, it's always a preference of a maintainer or the community. But usage of the
srcfolder makes perfect sense for me.I like the idea to have everything in the src folder so I know that's the code for my app. Everything else is related to the project config and compiling. I usually would use something like:
src/
I like the approach of using folder structures as namespaces, using the js export to facilitate things.
But this is just a matter of preference. 😉😉
Cool structure. I also like to facilitate things using named js exports (in every folder). Everything except the src folder makes perfect sense to me.
For the /src imagine it as the root for your code. The / is the root of your project, it's a way to separate concerns. Pretty common in other languages... loke having a Main() as an entry point of an application.
I like the idea of separation of concerns, but I regard the src folder like an API that wraps the response in a "data" object instead of responding with the actual info. I may be wrong though, I see many devs the prefer using the src folder.
It has A LOT of nesting and I believe the author of that article has completely different opinions than mine.
I am working on a similar deep nested project right now and I feel like the React components are not discoverable. I spend a lot of time searching for the right component.
I am bit against not using src folder , I have my reasons and may be pretty much why it became a standard .
For example one of project I worked was originally written using knockout (since it was poc they had loosely written the code and not in a well maintained structure )as a POC . The POC became mainstream and then I joined as a react dev to migrate it to react . There comes the challenge identify all that is needed to be migrated , another challenge was we had choosen to implement typescript and did not want javascript file to be polluting the source but the typescript cannot be bundled directly without being converted . We were sharing some files with other team so had to generate the javascript version anyway to support AMD . And later we implemented microfrontend . So better wrap your source files . Also need to have a folder for your test files . If req a configuration file ,but its optional and depends on project requirement
I was not aware that having a src folder is a standard. If it is, I may reconsider using it. If not, I believe the file structure to be much cleaner without it.
Agreed on having a folder for test files. As long as it has the root folder as parent.
@victorocna What do you keep in the functions folder? Is it helper functions?
exactly, helper functions. I keep in there anything like isLoggedIn, isDisabled, dateFormat, redirectTo and others
I would probably name it "utils".
Utils works fine as well :)
Models for?
For a todo app, I would save a todo model with props like name, created on, due on, etc. I also have some validation schemas and initial values. It is similar to mongoose schemas, if you are familiar with it.
Thank you