\
It's been quite a while since I wrote an [article](https://larswaechter.dev/blog/nodejs-rest-api-structure/) about how I structure my Node.js REST APIs. The article covered the approach of designing a well-organized and maintainable folder structure for Node.js applications.

\
So today I don't want to talk about Node.js APIs, but about the architecture of React applications and answer the same question from the previous article a second time:

\
> What should the folder structure look like?

\
And again: there’s **no perfect or 100% correct** answer to this question, but there are tons of other articles discussing this one on the internet too. This folder structure is also partly based on multiple of them.

\
One important thing to mention is that React does not really tell you how to organize your project, except the fact that you should avoid too much nesting and overthinking. To be exact they say: ([Source](https://reactjs.org/docs/faq-structure.html))

\
> React doesn’t have opinions on how you put files into folders. That said there are a few common approaches popular in the ecosystem you may want to consider.

\
Take a look at the linked source where you can read more about those common approaches. They won't be further discussed in this article.

\
The following structure and architecture is one that has proven maintainable and reliable for me. It might give you some help in designing your own project. Keep in mind that the following architecture is based on a application bootstrapped with [create-react-app](https://github.com/facebook/create-react-app) and written in **JavaScript**.

## Directory: root

```
react-project
├── node_modules
├── public
├── src
├── package.json
└── package-lock.json
```

\
This structure is nothing special and shouldn’t be new to you. It’s actually a basic [create-react-app](https://github.com/facebook/create-react-app) setup. The interesting part here is the content of the `src` folder which this article is about.

\
So what do we have in here?

\
```
react-project
├── api
├── components
├── i18n
├── modules
├── pages
├── stores
├── tests
├── utils
├── index.js
├── main.js
└── style.css
```

\
As you can see the application is primarily split into eight directories. From here on, we'll go top-down through the directories and examine each one.

\
Let’s start with the `api` directory.

## Directory: src/api

```
react-project
├── api
│   ├── services
│   │   ├── Job.js
│   │   ├── User.js
│   ├── auth.js
│   └── axios.js
```

\
The `api` directory contains all services that take care of the communication between the React application (frontend) and an API (backend). A single service provides multiple functions to retrieve data from or post data to an external service using the HTTP protocol.

\
`auth.js` provides functions for authentication and `axios.js` contains an [axios](https://www.npmjs.com/package/axios) instance including interceptors for the outgoing HTTP requests and incoming responses. Moreover, the process of refreshing JWTs is handled in here.

## Directory: src/components

```
react-project
├── components
│   ├── Job
│   │   ├── Description.js
│   │   └── Preview.js
│   └── User
│   │   ├── Card.js
│   │   ├── Create.js
│   │   └── List.js
```

\
If you're already familiar with React you should know that it's mainly component-based. The components are actually the heart of every React application. The whole application, at least the presentational view, is built of many small components.

\
So what is a component? [Source](https://reactjs.org/docs/components-and-props.html)

\
> Components let you split the UI into independent, reusable pieces, and think about each piece in isolation.

\
Imagine you have a website like Twitter or Facebook. The large website is made of many smaller pieces (components) that can be Buttons, Inputs or Widgets for example. Those pieces are put together to build even more complex and larger ones. Each component has its own lifecycle and state management, whereby you can share a component's state with other ones.

\
Components are reused multiple times within the application to save the developer from writing redundant code.

\
> [Don't repeat yourself (DRY)](https://de.wikipedia.org/wiki/Don%E2%80%99t_repeat_yourself)

\
Splitting the codebase into multiple components is not just a "React thing". It's a common pattern in software engineering to simplify the development process and the maintenance later on.

\
In React, a component is mostly a simple JavaScript function or a class. Usually, I create a new file for every single component. In some rare cases, I group multiple of them (functions or classes) into a single file. Imagine a `UserList.js` component that renders multiple elements of `UserListItem`:

\
```javascript
const UserList = ({ users }) => (
  <ul>
    {users.map(user => (
      <UserListItem key={user.userId} user={user} />
    ))}
  </ul>
)

const UserListItem = ({ user }) => <li>{user.name}</li>
```

\
Here, it makes sense to combine both into one file. Further, `UserListItem` is probably not even used by any other component than `UserList`.

\
Besides the components themselves, you can also add their stylesheets or tests to this directory.

## Directory: src/i18n

```
react-project
├── i18n
│   ├── de.json
│   └── en.json
```

\
`i18n` stands for **internationalization** and takes care of the language support of the application. The including JSON files are basically objects containing fixed constants as keys and their associated translations as values.

\
Therefore, the keys should be equal for each language file. Only the values (translations) differ from each other. You can easily query those language files later on by writing your own custom hook or component.

## Directory: src/modules

```
react-project
├── modules
│   ├── logger.js
│   └── session.js
```

\
This directory includes some global modules that might be used for logging or as wrapper for the browser's `LocalStorage` for example.

## Directory: src/pages

```
react-project
├── pages
│   ├── Home
│   │   ├── components
│   │   │   ├── Dashboard.js
│   │   │   └── Welcome.js
│   │   └── index.js
│   ├── Login.js
│   └── Profile.js
```

\
The `pages` directory includes the `react-router-dom` paths accessed while navigating through the application. Here, we collect multiple components into a single larger one to display a complete page view.

\
A page might contain its own `component` directory which includes "local" components that are only used on this page. For complex pages with a deep component tree, you might want to check out the [React Context API](https://reactjs.org/docs/context.html) which makes it much easier to pass props along the tree and to handle a global "page state".

## Directory: src/stores

```
react-project
├── stores
│   ├── language.js
│   └── user.js
```

\
This directory includes all global React states that can be accessed from any component within the application. While [Redux](https://react-redux.js.org/) is probably the most popular solution for managing global state I prefer to use [zustand](https://github.com/pmndrs/zustand). It's very easy to get started with and its API is really straightforward.

## Directory: src/tests

```
react-project
├── tests
│   ├── language.test.js
│   └── utils.test.js
```

\
The `tests` directory includes tests that do not belong to certain components. This could be tests for the implementation of algorithms for example. Moreover, I validate and compare the keys of the language files I mentioned above to make sure I did not miss any translation for a given language.

## Directory: src/utils

```
react-project
├── utils
│   ├── hooks
│   │   ├── useChat.js
│   │   ├── useOutsideAlerter.js
│   │   ├── useToast.js
│   ├── providers
│   │   ├── HomeContextProvider.js
│   │   ├── ToastContextProvider.js
│   ├── colors.js
│   ├── constants.js
│   ├── index.js
```

\
Here, we have a bunch of utilities like: custom hooks, context providers, constants and helper functions. Feel free to add more stuff here.

## All together

Last but not least a complete overview of the project structure:

\
```
react-project
├── api
│   ├── services
│   │   ├── Job.js
│   │   ├── User.js
│   ├── auth.js
│   └── axios.js
├── components
│   ├── Job
│   │   ├── Description.js
│   │   └── Preview.js
│   └── User
│   │   ├── Card.js
│   │   ├── Create.js
│   │   └── List.js
├── i18n
│   ├── de.json
│   └── en.json
├── modules
│   ├── logger.js
│   └── session.js
├── pages
│   ├── Home
│   │   ├── components
│   │   │   ├── Dashboard.js
│   │   │   └── Welcome.js
│   │   └── index.js
│   ├── Login.js
│   └── Profile.js
├── stores
│   ├── language.js
│   └── user.js
├── tests
│   ├── language.test.js
│   └── utils.test.js
├── utils
│   ├── hooks
│   │   ├── useChat.js
│   │   ├── useOutsideAlerter.js
│   │   ├── useToast.js
│   ├── providers
│   │   ├── HomeContextProvider.js
│   │   ├── ToastContextProvider.js
│   ├── colors.js
│   ├── constants.js
│   ├── index.js
├── index.js
├── main.js
└── style.css
```

\
That’s it! I hope this is a little help for people who don't know how to structure their React application or didn’t know how to start. Feel free to give any suggestions.

\
*Previously published [here](https://larswaechter.dev/blog/react-project-structure/).*

BUNCH

Facebook

Twitter

Coding Guru of 2022

Nominated for Coding Guru of 2022

Too Long; Didn't Read

Cassandra Forward a free Cassandra-focused community event

How I Structure my React Projects

Too Long; Didn't Read

Companies Mentioned

@larswaechter

RELATED STORIES