Organizing folder and file structure in React

Preface

Good day, colleagues! In this article, I share my way of organizing folders and files for React/Next projects. I am a full-stack developer with 10+ years of experience in commercial development, I have developed many startups in various teams, and I have developed several startups alone, incl. of your own.

In medium and large projects there is a huge number of self-written modules and components, and it is important to optimize their storage, make the file structure simple and understandable for yourself and other programmers who will work on the project. But how can we ensure that a wide variety of components, scripts and modules are stored so that the file tree does not turn into a mess, and the search for the required component occurs quickly, so that you do not have to search for it in a long list of files?

This way of organizing files by architecture MVC (model, view, controller) does not claim to be the ultimate truth, at the same time, this is an approach that I came to after going quite a long way, and an approach that has proven itself to be very convenient in many projects. Therefore, if you find the information useful, take it into account. If you have your own approach, you can share it in the comments, or write a separate article. I do not set a goal to create a holivar on the topic that this method is impeccable and better than all others, this is just one of the methods.

I will list all the folders I use; if you realize that you don’t need any folder in the project, don’t create it. The opposite is also true – if you need any folder that is not in this article, you can always improve this structure by modifying it for yourself.

Let's decide on the goal

What do we want when we think about the file structure? Firstly, each file with code should have its own specific location, depending on what is in this file. When we want to find a page, we know exactly in which folder it is located. When we want to find a section, script, or something else, it’s the same. If we put all the components in the components folder, in a medium/large project we will have a long list, and we will need to spend extra time scrolling through it in search of the required component. This means you need to create subgroups of folders. This is what the article is about.

Beginning of work:

After initializing the project, we will clean the project from junk files (standard style files, starting template, etc.) and create the main folders. If you have a configuration with a src folder, then in it, if not, then in the project root.

To store JSX components I create a react folder.

Why do we need this extra folder? So that folders with page components, ui components, and other “layout” are next to each other.

When we have the components and pages folders in the root, they are sorted alphabetically, it often happens that we need to switch between the pages and components files, and each time flipping through the tree in search of these folders is long and inconvenient.

It’s another matter when they are side by side, in the same folder!

In the react folder we will immediately create the following folders:

components – it will contain components: individual reusable parts of the user interface. We will additionally group them into folders inside the components folder, I will write about this further below, with a detailed explanation.

pages – it will contain components of full pages. the folder is created only for react, or when next uses a router other than the classic one, when the page files are located in the pages folder in the project root

views – it will contain components of full pages that can actually be used on different pages. If such a situation is expected in the project, for the sake of order it makes sense to store all the pages in the views folder, and call these components in the components in the pages folder. if such situations are not expected, you can discard this folder in react. in next.js I create this folder anyway so that the page file folders are next to the folders of other JSX components.

sections – it will contain components that are sections of pages. a section is, let's say, one of the semantic parts of the page. We will store all sections in this folder, grouping them into folders with the page name. why not create such a folder in the folder of each page in pages? It's not uncommon for a section from one page to be used on another page, but not every page needs to be split into sections. Using this approach, if we need to open a file in a particular section, we will find it very quickly.

popups – it will contain components of modal windows. As a rule, a folder with a master component is created, and next to it there are folders with modals created on the basis of this component

I deliberately did not place the last 3 folders in the components folder, for the reason that we will have enough folders in components, and these folders should be quickly accessible. What exactly will be located in components needs a detailed description, and is located towards the end of the article.

To store JS logic, create a scripts folder

We will create the following subfolders in it:

helpers – it will contain auxiliary functions that can be called in different parts of the project.

hooks – custom React hooks

backend – functions that interact with the backend. they send a request and return data. all other logic occurs at the place where they are called

To store global styles and fonts, create a styles folder

Global styles are general styles that apply to the entire project. For individual components, I prefer to store styles in the component folder, in a separate file. I will show using scss as an example, because… I use it most often. So, let's create the files:

global.scss – this file will be imported into the application, and the rest of the style files from the styles folder will also be imported into this file. Also in this file, standard css styles are reset, and fonts are imported.

text.scss – in this file I write atomic styles for the text. As a rule, in large projects everything is standardized – headings, subheadings, texts, etc.

variables.scss – this file will store the rest of the css variables

animations.scss – CSS animation styles are stored in this file accordingly

If the project uses local fonts, you should create a fonts folder in the styles folder and place them there

To store JS variables, create a constants folder

It will contain JS files in which the variables will be grouped according to the meaning of the file name. For example, in this folder I may have files such as:

settings.js – any settings

api.js – a list of all backend API addresses, these are the variables that are used in requests to the server

secret.js – various tokens and secret keys. next to this file there is secret.example.js, which contains variables, but not their values, and secret.js itself is located in .gitignore

urls.js – various internal and external links for use in different parts of the project. it’s easier to immediately change one variable and automatically apply the change everywhere where the link is used.

And so on.

For the global state, create a folder store

And in it we create subfolders for files of the type of global state that you use (for example actions, reducers, etc.). Personally, I use in a significant number of cases, unfortunately not so well known, but very simple And proven to be effective module useGlobalHookon which I wrote a mini-guide: Easy-to-use global state storage for React or Next: useGlobalHook.

To store different localizations, create a folder locales

Only if it is expected that the project interface will be available in more than one language. Then for each language we will create a separate js file containing variables with the text of the required localization.

So, we have created the main folders!

Now let's dive into the contents of the /react/components folder. As I wrote above, if we simply push all the folders with components into this folder, we will end up with a long list that is long and inconvenient to scroll through. Therefore, we will group the components into folders.

While explaining this concept to colleagues, I was faced with the fact that it is often not obvious which component belongs to which subgroup. Therefore, the next part of the article will not just be a description of the folders inside the components folder, but a very detailed explanation of which components should be in this folder, with examples in the form of screenshots.

Let me emphasize once again: all the folders that will be discussed below must be created in the /react/components folder!

Containers folder

It contains components that perform the function of a wrapper, i.e. components that return children.

For example, this could be a carcas component – a common wrapper for all pages that outputs header components in addition to children (a cap) and footer (basement), and also containing meta tags (with the ability to transfer custom tags/states via props).

An example of a return from a carcas container:

Page layout containers (wrappers, layouts), standardized text output components, universal container components (such as a universal collapsing and expanding accordion, on the basis of which you can create individual accordion components for specific situations). Well, you understand.

Inputs folder

It contains separate components thanks to which the application user can enter any information – text fields, checkboxes, switches, buttons, selectors, and so on.

Examples of components that should be in the inputs folder

Forms folder

Contains components that are a combination of several components from the inputs folders. This could be, for example, a form for entering a login and password (only text fields and a button), or a form for subscribing to an e-mail newsletter.

Examples of components that should be in the forms folder

Sliders folder

Contains custom slider components. Those. if we need to display a slider somewhere, we usually use a module, this module entails a bunch of settings and so on. For convenience, we create a separate component in this folder, in which we make the slider look the way we want, and with the help of props we make it as easy as possible to use and re-use a specific slider display type from the UI-kit of the project.

Folders icons and illustrations

Only for Next.js, because surprisingly, for now It cannot import icons as components directly from svg (while in React you can). As is clear from the names of the folders, they contain JSX components with svg code. There is a separate folder for illustrations so that the icons do not get mixed up with svg illustrations.

cards folder

It contains components that display a certain amount of information about any individual entity. Most often, when these components are used in parts of the project, they are output in a loop through map. As an example, a product card in the product list of an online store, a “review” element from a list of reviews, banners (that are not sliders), and so on.

Examples of components that should be in the cards folder

ui folder

UI stands for user interface. This folder will contain the user interface components do not fall into any of the categories described above. For example header, footer, breadcrumbs, pagination, etc.

Very important Before creating a component folder in the ui folder, check whether it falls under the categories described above, and if it does, create it in the required folder.

Great, the file structure for the project is ready!

Thanks to this approach, we have achieved a clear and understandable folder structure in which it is easy to find any file you need, due to the fact that there will not be too many folders or files in any of the folders. We immediately go into the folders according to their meaning and find the required file.

A few more recommendations:

When creating folders for the components themselves, name them meaningfully. While experimenting, I tried naming folders/files using Camel Style and using_underscoreand found that the most pleasant to perceive approach is where in the file/folder name dots are used instead of spaces

I recommend creating a folder for each component where the component code will be stored in index.jsx (or index.tsx), and also in the same folder there will be a separate file with the component styles (whatever method you use – be it scss or styled).

Don't create multiple components in one file, and even more so a component within a component. The first is not clear, and the second completely harms optimization.

At the same time, try to isolate each part of the interface into a separate component and use it. Because One of the main beauties of React/Next that we talk about is the modular approach.

The code will become much more clearly, if you don’t shove the lion’s share of the layout into one file (although this will also work), but collect individual parts into separate “puzzles”, and from these “puzzles” assemble the overall picture. And each “puzzle” can itself consist of several “puzzles”.

Simply put – create components from other components, which in turn are created from other components that you have created. Every part that can be isolated into a component must be isolated into a component.

Here, for example, is a screenshot from the code of one of the pages of my site, which is a fairly long landing page:

Imagine what the page would look like if the JSX code for all sections were not in separate components, but right on this page? It would be a complete horror, impossible to navigate. And then we look – and it’s immediately clear which section is which. You can go to it directly from this file and edit it if necessary.

Don't be lazy to create and fill out the readme.md file in the project root!

There are a bunch of markdown editors in which you can create formatted text, without knowledge of md markup. In this file, describe the structure of the project so that it is easier for other programmers (including you) to navigate the file structure of the project. Also describe in it how to deploy a project for the first time, how to deploy for development and for production. Attach links to project materials (design in figma, API documentation, etc.

GIT understands markdown, and on your project page in Git, under the list of files there will be instructions with all the links. This is very cool and convenient, everyone will appreciate it – both teammates and customers, and even if you work alone on your own project, this file will be useful to you.

I wish you good luck in developing your projects!

Tell us in the comments what method of organizing folders and files you use in your projects, and whether you were able to adopt any techniques from this article. If you have ideas on how else this structure can be improved, write too. Most likely, ideas for improvement will come to me over time, in which case I will supplement the article.