Creating yet another react boilerplate — Part 1 : the why

When I began learning React, I found an excellent course on Internet based on videos and coding. In this course, the author shows how to configure a react app from scratch : how to use Babel, how to configure webpack and so on. At the time I didn’t know create-react-app yet. It was very interesting to know how to configure a react app but it was also very boring and complicated, especially as a beginner, to set things up.

When I discovered create-react-app (CRA), It was like a deliverance for me. It was a gift fallen from heaven. For those who don’t know create-react app, it is a CLI tool that allows us to Create React App with no build configuration.

Since then, the team and I used create-react-app in all our projects. My colleague (and friend) Aymen Chebbi collaborated with me more than one time.

After some projects, Aymen and I noticed that using create-react-app is not as good as It seems to be. With every new project that we started, we were repeating ourselves. We had to :

• Install the usual libraries (redux, react-redux, axios, …).
• Eject the project to handle sass and decorator
• Configure eslint
• Configure env file
• and last but not least, create our project structure

The last step is the most important for Aymen and I because it improves our collaboration. Our preferred project structure is :

Our preferred project structure

Besides all this configuration, even if VS Code makes it easy to generate js files representing components, we still have to make other tasks like creating new folders with the same name as the components, adding new js files and scss files having the same name and then IMPORTING the scss files in the corresponding js files.

Since we worked with Redux, we had to configure Store for every project. Every one using redux knows that to work with it, we have to compose middlewares, combine reducers and create store. Moreover, for each new reducer, we have to further create a reducer file, maybe an action creators file and action types file. Then we have to add that new reducer file in the list of combined reducer.

In short, we spent a lot of time configuring, which was boring & tedious for us. It felt as if we returned to the time when we didn’t know create-react-app: configuring, configuring and configuring again.

We found solutions that are similar to create-react-app but with a lot more features…, but the problem is that they contain more configuration than we need.

So we had the idea of creating our own CUSTOM BOILERPLATE wrapped by a CUSTOM CLI. To people who don’t know the meaning of “boilerplate”, a boilerplate is a template that you can clone and reuse for each new project. The reason behind a CLI is to automatically generate a component or reducer folders as we want.

The idea is marvellous but how can we make it possible.

Existing Solutions :

Searching the web, we came across multiple options that can achieve some of what we need, here is a summary of what we found :

cli-react :

cli-react is a little neat command line tool created by some nickverstocken, that can generate (custom) react projects and components. It comes with few extras like some pre installed node modules and custom file architecture.

Digging inside its source code, we find that it’s just a wrapper around create-react-app that starts and modifies its outputted files.

Pros :

• Different file architecture
• Preinstalled node_modules (mobX, node-sass-chockidar…)
• Different options for component generation (class/functional component, with/without css file, connected or not to mobX…)

Cons :

• File architecture not customizable.
• Does not work correctly on Windows : tries open scripts instead of running it
• Packs really annoying bugs : script aborts if a node module installation yields warnings
• Lacks features that we need : ESLint, Decorators
• Can’t substitute MobX for Redux
• Live reloading for sass files is either slow or doesn’t work most of the times.

If you want to learn more about cli-react checkout its repo

create-react-app with a custom react-script:

We’re familiar with ejecting our CRA project, something we do all the time. But searching for boilerplates for the first time has led us to understand how that actually works (silly me) and where the Webpack config was (magically) hidden.

In fact scripts that you use to start, build or eject your CRA project are bundled in an npm module along (Webpack config), called react-scripts.

That means running npm start is just executing react-scripts start and ejecting will just expose the code source for that npm module.

You knew that already ? Here’s a little known fact : create-react-app packs an UNDOCUMENTED flag option to load a custom react-script

Basically this means you change CRA build configuration without ejecting ! Neat right ?

Here’s how to use it :

Use of custom-react-scripts

You can learn more on how to do it here

Pros

• Builds on top CRA
• Change build configuration without ejecting

Cons

• Can’t customize file structures.
• Can’t preinstall node_modules

react-boilerplate :

React boilerplate is, as described in their GitHub repo, “A highly scalable, offline-first foundation with the best developer experience and a focus on performance and best practices”.

In fact react boilerplate packs a ton of features from start including css and js hot reloading, i18n support, and a bunch of preinstalled node_modules, without forgetting the cli to generate components, containers, routes, selectors and sagas …

Use of react-boilerplate CLI

Last but not least react boilerplate comes with a heavy/big file architecture that feels very Angular(y)

Pros :

• Long list of features

Cons :

• Heavy/complex setups
• Packs a bunch of features/module that we don’t/ever going to use

If you want to learn more about react-boilerplate checkout their website

Our boilerplate

All of the above solutions have their pros and cons but don’t meet our needs for the perfect boilerplate.

A Perfect boilerplate, in our opinion, should :

• Have CLI to generate project with our desired file structure and components with different options (class/functional, connected to Redux…)
• Pack features that we usually need to eject in order to add (sass loader…)
• Pre-install popular node_modules (redux, axios, etc…)

Next part

In the next part, Creating yet another react boilerplate — Part 2: the how, we will learn technically how to create our boilerplate based on needs mentioned above.

PS : this article is written by Aymen and I, two curious full stack developer.