Organize a Large React Application and Make It Scale

In this article, I’ll talk you through the decisions I make when building React application: picking tools, structuring files, and breaking components up into smaller pieces.

Once you’ve done that you can always import files relative to the directory:

Whilst this does tie your application code to Webpack, I think it’s a worthwhile trade-off because it makes your code much easier to follow and imports much easier to add, so this is a step I’ll take with all new projects.

For example, we have a folder called that contains all components relating to the shopping cart view, and a folder called that contains code for listing things users can buy on a page.

Following on from the previous rule, we stick to a convention of one React component file, and the component should always be the default export.

Normally our React files look like so:

In the case that we have to wrap the component in order to connect it to a Redux data store, for example, the fully wrapped component becomes the default export:

You’ll notice that we still export the original component; this is really useful for testing where you can work with the “plain” component and not have to set up Redux in your unit tests.

I’ll talk you through the decisions I make when building React applications :picking tools, structuring files,and breaking components up into smaller pieces @javascriptX: Organize a Large React Application and Make It Scale

☞

#reactjs

Large React Application

In this article, I’ll discuss the approach I take when building and structuring large React applications. One of the best features of React is how it gets out of your way and is anything but descriptive when it comes to file structure. Therefore you’ll find a lot of questions on StackOverflow and similar asking how to structure applications. This is a very opinionated topic, and there’s no one right way. In this article, I’ll talk you through the decisions I make when building React application: picking tools, structuring files, and breaking components up into smaller pieces.

It will be no surprise to some of you that I’m a huge fan of Webpack for building my projects. Whilst it is a complicated tool, the great work put by the team into version 2 and the new documentation site make it much easier. Once you get into Webpack and have the concepts in your head you really have incredible power to harness. I use Babel to compile my code, including React-specific transforms like JSX. And the webpack-dev-server to serve my site locally. I’ve not personally found that hot reloading gives me that much benefit, so I’m more than happy with webpack-dev-server and its automatic refreshing of the page.

I also use the ES2015 module syntax (which is transpiled through Babel) to import and export dependencies. This syntax has been around for a while now and although Webpack can support CommonJS (aka, Node style imports). It makes sense to me to start using the latest and greatest. Additionally, Webpack can remove dead code from bundles using ES2015 modules which, whilst not perfect, is a very handy feature to have. And one that will become more beneficial as the community moves towards publishing code to npm in ES2015.

resolution to avoid nested imports

One thing that can be frustrating when working on large projects with a nested file structure is figuring out the relative paths between files. You’ll find that you end up with a lot of code that looks like this:

, so you have to add it too else Webpack won’t be able to import files that you’ve installed with npm or yarn.

directory:

Whilst this does tie your application code to Webpack, I think it’s a worthwhile trade-off because it makes your code much easier to follow and imports much easier to add, so this is a step I’ll take with all new projects.

There is no one correct folder structure for all React applications – as with the rest of this article, you should alter it for your preferences – but the following is what’s worked well for me.

. This contains only code that ends up in your final bundle, and nothing more. This is useful because you can tell Babel (or any other tool that acts on your app code) to just look in one directory and make sure that it doesn’t process any code it doesn’t need to. Other code, such as Webpack config files, lives in a suitably named folder. For example, my top level folder structure often contains:

, and so on.

trick I mentioned earlier which simplifies all imports.

, but I’ve found that on larger projects this gets overwhelming very quickly.

A common trend is to have folders for “smart” and “dumb” components (also known as container and presentational components), but personally I’ve never found explicit folders work for me. Whilst I do have components that loosely categorize into “smart” and “dumb” (I’ll talk more on that below), I don’t have specific folders for each of them.

that contains code for listing things users can buy on a page.

folder:

This is a rule that I find myself breaking sometimes – sometimes the extra prefix can clarify, particularly if you have 2-3 similarly named components, but often this technique can avoid extra repetition of names.

, and you can even apply specific Webpack plugins to these files if you need to.

Whichever naming convention you pick, the important thing is that you stick to it. Having a combination of conventions across your codebase will quickly become a nightmare as it grows and you have to navigate it.

Following on from the previous rule, we stick to a convention of one React component file, and the component should always be the default export.

Normally our React files look like so:

In the case that we have to wrap the component in order to connect it to a Redux data store, for example, the fully wrapped component becomes the default export:

You’ll notice that we still export the original component; this is really useful for testing where you can work with the “plain” component and not have to set up Redux in your unit tests.

, and so on.

“Smart” And “Dumb” React Components

I briefly mentioned the separation of “smart” and “dumb” components, and that’s something we adhere to in our codebase. Although we don’t recognize it by splitting them into folders, you can broadly split our app into two types of components:

You can read more about how we aim for “dumb” components in my blog post on Functional Stateless Components in React. These components make up the majority of our application and you should always prefer these components if possible, they are easier to work with, less buggy and easier to test.

Even when we have to create “smart” components we try to keep all JavaScript logic in its own file. Ideally, components that have to manipulate data should hand that data off to some JavaScript that can manipulate it. By doing this the manipulation code can be tested separately from React, and you can mock it as required when testing your React component.

One thing we strive for is to have many small React components, rather than fewer larger components. A good guide to if your component is getting too big is the size of the render function. If it’s getting unwieldy, or you need to split it up into many smaller render functions, that may be a time to consider abstracting out a function.

function is a good guideline. You might also use the number of props or items in state as another good indicator. If a component is taking seven different props that might be a sign that it’s doing too much.

React allows you to document the names and types of properties that you expect a component to be given using its prop-types package. Note that this changed as of React 15.5, previously proptypes were part of the React module.

By declaring the names and types of expected props, along with whether they are optional or not, you to have more confidence when working with components that you’ve got the right properties, and spend less time debugging if you’ve forgotten a property name or have given it the wrong type. You can enforce this using the ESLint-React PropTypes rule

Although taking the time to add these can feel fruitless when you do, you’ll thank yourself when you come to reuse a component you wrote six months ago.

We also use Redux in many of our applications to manage the data in our application, and structuring Redux apps is another very common question, with many differing opinions.

The winner for us is Ducks, a proposal that places your actions, reducer and action creators for each part of your application in one file.

. Your folder structure would look like so:

you place all code for those, which normally will look like:

This saves you having to import actions and action creators from different files, and keeps the code for different parts of your store next to each other.

Although the focus of this article has been on React components, when building a React application you’ll find yourself writing a lot of code that’s entirely separated from React. This is one of the things I like most about the framework; a lot of the code is entirely decoupled from your components.

works well here – the specific name doesn’t matter but a folder full of “non-React components” is really what you’re after.

API:

Keeping your logic out of components like this has some really great benefits:

As mentioned above, we test our code very extensively and have come to rely on Facebook’s Jest framework as the best tool for the job. It’s very quick, good at handling lots of tests, quick to run in watch mode and give you fast feedback, and comes with some handy functions for testing React out of the box. I’ve written about it extensively on Sitepoint previouslyso won’t go into lots of detail about it here, but I will talk about how we structure our tests.

, you end up with really long imports. I’m sure we’ve all come across this:

These are hard to work with and hard to fix if you change directory structures.

, but they live alongside the source code, with the same name otherwise:

As folder structures change it’s easy to move the right test files, and it’s also incredibly apparent when a file doesn’t have any tests, so you can spot those issues and fix them.

There are many ways to skin a cat, and the same is true of React. One of the best features of the framework is how it lets you make most of the decisions around tooling, build tools and folder structures and you should embrace that. I hope this article has given you some ideas on how you might approach your larger React application. But you should take my ideas and tweak them to suit you and your team’s preferences.