Better file structure in React projects

Publish Date: Aug 20 '21

153 27

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 public folder should be a good fit;
have some custom hooks that you are proud of? keep them easy to find in the hooks folder;
want to include yet another css file? store them in the css folder.

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.

api
components
css
data
functions
hooks
models
pages
public
LICENSE
README.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!

Comments 27 total

Dennis Groß (he/him)Aug 20, 2021
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.
- Victor OcnarescuAug 20, 2021
  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?
  - Dennis Groß (he/him)Aug 20, 2021
    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.
    - Victor OcnarescuAug 21, 2021
      Keeping it practical and starting simple is great advice!
ErnestoAug 21, 2021
@victorocna What do you keep in the functions folder? Is it helper functions?
- Victor OcnarescuAug 21, 2021
  exactly, helper functions. I keep in there anything like isLoggedIn, isDisabled, dateFormat, redirectTo and others
  - Amohammadi2Aug 21, 2021
    I would probably name it "utils".
    - Victor OcnarescuAug 21, 2021
      Utils works fine as well :)
Itay SchechnerAug 21, 2021
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.
- Victor OcnarescuAug 21, 2021
  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)
  - Itay SchechnerAug 21, 2021
    That's really cool
- Victor OcnarescuAug 21, 2021
  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
  - Itay SchechnerAug 21, 2021
    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 helpers folder.
    
    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.
RajshekharAug 21, 2021
Models for?
- Victor OcnarescuAug 21, 2021
  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.
  - RajshekharAug 22, 2021
    Thank you
dmiku123Aug 21, 2021
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
- Victor OcnarescuAug 21, 2021
  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.
Raí B. ToffolettoAug 21, 2021
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/
- api
- assets
- common (useful methods)
- components
- database (when used with typeorm)
- hooks
- reducers (with redux)
- views
- index.jsx (entry point)
- settings.js
- theme.js (in case of MaterialUI).
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. 😉😉
- Victor OcnarescuAug 22, 2021
  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.
  - Raí B. ToffolettoAug 23, 2021
    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.
    - Victor OcnarescuAug 23, 2021
      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.
Jakub DubecAug 22, 2021
Hello, I just want to add a quick note to the meaning of the src folder. 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 .github and other stuff that comes in the way during the project.
- Victor OcnarescuAug 23, 2021
  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?
  - Jakub DubecAug 23, 2021
    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 src folder 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:
    
    github.com/timescale/timescaledb
    
    github.com/rizinorg/cutter
    
    github.com/microsoft/terminal
    
    github.com/paramiko/paramiko (module name instead of src)
    
    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 src folder makes perfect sense for me.
Victor OcnarescuAug 23, 2021
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.

Add comment

Victor Ocnarescu @victorocna