I didn’t like create-react-app so I created my own boilerplate

Contrary to the popular practice of hiding the config, here’s a project that exposes it

A nice giant image to make the article more attractive. Prezly office in Leuven, Belgium.

I always liked to see how things were working, get into the details of which part does what, this curiosity perfectly reflects on web development path.

When I was learning web development this has always been what pushed me forward, learning more and more to answer a never ending stream of questions fuelled by the knowledge I was acquiring.


Is a boilerplate for jump starting your React projects, it is absolutely mind-blowing how easy it is to use it.

# Install the package globally with npm
$ npm i -g create-react-app
# And then use the default script to start
# as many projects as you like
$ create-react-app testFolder

It is a fantastic learning tool if you start from scratch because all the magic is hidden from your view, you just focus on React and let create-react-app take care of the details.

Is it really the best way to learn how to use React?

Dan Abramov — The Melting Pot of JavaScript

In this speech Dan Abramov talks about the config diatribe in JavaScript.
It is a really interesting overview of JavaScript and its ecosystem, I highly recommend watching it.

Configuration should not stand in the way of getting started.

I share his sentiment, I actually started using React on codepen, where the configuration necessary to use React is close to zero making it possible to concentrate on just React.

The way create-react-app solves this problem is by hiding all the config by default, so after starting your project you are not exposed to Babel, Webpack, dev/prod environment, or any other config.
It gives you a package.json file with 4 scripts to either run the app locally, run tests, build the bundle, or eject the config to check how things work in the background.

The config issue with create-react-app

While I fully embrace the idea of create-react-app to get new developers into the scene, there’s something I feel is missing.
You start learning with a tool that does everything for you, but when you are ready to know how things really work under all that, what are you supposed to do?
With create-react-app you have an eject script that can uncover all the config that is hidden beneath.
If you feel so adventurous to do it, you will find yourself into a really huge and scary config, meant to do a lot of stuff and designed to not be exposed to the end user.

This creates a problem that I feel is not being properly addressed.
We are training new developers with tools they will not be ready to maintain.

The memes about ejecting create-react-app are everywhere.

React does require some amount of configuration to get started, if we decide to not expose new developers to this aspect of development we are failing them, teaching them only the good parts and hiding the difficult ones. 
This will probably give us a bigger number of newcomers but it doesn’t give us developers ready to take our place.

I get that the reasoning behind create-react-app is to learn React without worrying about the configuration, but the elements of create-react-app which insulate the user from having to be exposed to the config also make it difficult to understand its internals, you should know the basics of how it works.

Enter simple-react-app

Lemme add a react logo so it looks professional.

To learn how to deal with a config I inspected and used other developers’ configs until I knew enough to come up with my own, learning from other developers is one of the best and fastest way to improve so I wanted to share this with others that might still be scared of how to do it or simply don’t know anything about it.


Initially it was just a boilerplate that could be cloned and changed to jump-start a react application, with a basic and easy config that provides enough for a small project to work and requires little gradual tinkering to expand beyond the basics.

I keep the minimal config exposed so anyone could analyse and study it, play with it, and improve it.
I always change it on my own projects to be more specific. Adding this to the core package would only increase the complexity quite a lot, and I want to keep it as minimal and functional as possible on the boilerplate.

Some time ago, since I was tired of having to clone it every time, I decided to write a script in Node to turn that simple boilerplate into a global npm package with the same functionality as create-react-app.

# Install the package globally with npm
$ npm i -g simple-react-app
# And then use the default script to start
# as many projects as you like
$ simple-react-app testFolder

Same commands as create-react-app, but with easy-peasy logic behind it.

The simple-react-app configuration is bare minimum, just enough to get a dev environment and an optimised production bundle.
All the cool things are taken out and can be incrementally added manually by every user, thus teaching how to work with a configuration step by step.


So what do you get with simple-react-app that create-react-app doesn’t have?

The whole exposed configuration needed for React to work in an efficient way!
It includes:

  • A 75 lines webpack file with development and production enviroments
  • A basic babel config for hot-reloading & treeshaking
  • Airbnb ESLint specs for better code formatting.

Why is all this important?

Because that’s what you should know to create a production-ready application. You can’t ship MBs of trash, working slowly on some browsers and not working at all in others.

Want to know more about simple-react-app?
Check the GitHub repository or install it from npm!

Feel free to open issues or send me a message, even on Twitter, I’ll answer as best as I can!

We owe it to the new WebDevs who are new to the JavaScript ecosystem, to build on top of our work and to make it clear for them what pillars are being used to build our apps.
Only by sharing our tools will our ecosystem thrive and grow healthy.