DEV Community

Cover image for Better file structure in React projects
Victor Ocnarescu
Victor Ocnarescu

Posted on

Better file structure in React projects

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!

Discussion (27)

Collapse
itays123 profile image
Itay Schechner

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.

Collapse
victorocna profile image
Victor Ocnarescu Author

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

Collapse
itays123 profile image
Itay Schechner

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.

Collapse
victorocna profile image
Victor Ocnarescu Author • Edited

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)

Collapse
itays123 profile image
Itay Schechner

That's really cool

Collapse
gdenn profile image
Dennis Groß

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.

Collapse
victorocna profile image
Victor Ocnarescu Author

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?

Collapse
gdenn profile image
Dennis Groß

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.

Thread Thread
victorocna profile image
Victor Ocnarescu Author

Keeping it practical and starting simple is great advice!

Collapse
sibyx profile image
Jakub Dubec

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.

Collapse
victorocna profile image
Victor Ocnarescu Author

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?

Collapse
sibyx profile image
Jakub Dubec

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:

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.

Collapse
raibtoffoletto profile image
Raí B. Toffoletto

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. 😉😉

Collapse
victorocna profile image
Victor Ocnarescu Author

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.

Collapse
raibtoffoletto profile image
Raí B. Toffoletto

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.

Thread Thread
victorocna profile image
Victor Ocnarescu Author

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.

Collapse
dmiku123 profile image
dmiku123

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

Collapse
victorocna profile image
Victor Ocnarescu Author

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.

Collapse
exenestecnico profile image
Ernesto

@victorocna What do you keep in the functions folder? Is it helper functions?

Collapse
victorocna profile image
Victor Ocnarescu Author

exactly, helper functions. I keep in there anything like isLoggedIn, isDisabled, dateFormat, redirectTo and others

Collapse
ashkanmohammadi profile image
Amohammadi2

I would probably name it "utils".

Thread Thread
victorocna profile image
Victor Ocnarescu Author

Utils works fine as well :)

Collapse
brawl profile image
Brawl

Personally I think this here is also great: taniarascia.com/react-architecture... but it has a lot of nesting which could be reduced.

Collapse
victorocna profile image
Victor Ocnarescu Author

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.

Collapse
rajshekhar profile image
Rajshekhar

Models for?

Collapse
victorocna profile image
Victor Ocnarescu Author

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.

Collapse
rajshekhar profile image
Rajshekhar

Thank you