How to write a minimal React boilerplate from scratch

4 min readJul 6, 2019

Setting up your own React project from scratch can seem daunting if you’ve never done it before, but I want to show you how quick and easy it can be to get a basic project set up with everything you need to start writing your next React app.

Facebook’s create-react-app is an extremely convenient way to quickly get a boilerplate React project set up, but I find it comes with a lot of packages and configuration that I don’t always need, and I prefer to have a little more fine-grained control over my setup. So today I’m going to show you how you can make your own from scratch.

Let’s do it!

Basic setup

The first thing we need to do is create a new empty directory for our project. I’m going to call it react-boilerplate, but you can call it whatever you want. From your terminal:

mkdir react-boilerplate

Then cd into your newly created directory:

cd react-boilerplate

NOTE: If you’re going to use version control, now would be a good time to git init and add a .gitignore file.

We’re going to need a package.json file to manage our dependencies. Let’s initialise one:

npm init -y

NOTE: The -y flag automatically accepts the default configuration without npm asking you any questions. This is fine for our purposes.

Install dependencies

Next, let’s install our dependencies. The only production dependencies we’ll need for our basic setup are React and ReactDOM, so let’s install those:

npm i react react-dom

Then we’ll need a bunch of dev dependencies. We need webpack to bundle and compile our code, and the webpack-cli to interact with it. webpack-dev-server provides us with a live-reloading development server. html-webpack-plugin isn’t entirely necessary in our case, but it allows us to keep our source files separate from our distribution files and auto-generates our index.html file with a script tag pointing to our bundled JavaScript. The babel-loader tells webpack to run our code through babel. @babel/core is the core babel package which will use @babel/preset-env to transpile our modern ES6+ JavaScript down to a more browser-friendly version, and @babel/preset-react to compile our JSX to JavaScript.

npm i -D webpack webpack-cli webpack-dev-server html-webpack-plugin babel-loader @babel/core @babel/preset-env @babel/preset-react

That’s all we really need to install. Let’s start writing some code!

Build project structure and config files

Let’s build out a couple of empty directories and files which we’ll then start to fill out:

mkdir src src/components && touch src/index.js src/index.html src/components/App.js .babelrc webpack.config.js

Great! Now your file structure should look like this:

react-boilerplate
├── node_modules/
├── src
│   ├── components/
│   │   └── App.js
│   ├── index.html
│   └── index.js
├── .babelrc
├── package-lock.json
├── package.json
└── webpack.config.js

Now copy the following into your webpack.config.js:

const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');module.exports = {
  plugins: [
    new HtmlWebpackPlugin({
      template: path.resolve(__dirname, 'src/index.html'),
    }),
  ],
  module: {
    rules: [
      {
        test: /\.(js|jsx)$/,
        exclude: /node_modules/,
        use: ['babel-loader'],
      },
    ],
  },
};

And this into your .babelrc:

{
  "presets": ["@babel/preset-env", "@babel/preset-react"]
}

Lastly, you’ll need a template for html-webpack-plugin with an identifiable element for your React app to mount to. Add this to src/index.html:

<!DOCTYPE html>
<html lang="en"><head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>React Boilerplate</title>
</head><body>
  <noscript>You need to enable JavaScript to run this app.</noscript>
  <div id="root"></div>
</body></html>

Awesome! Now we just need some React!

Adding the React

Now comes the fun part. Let’s create the entry point to our application and tell React where to mount to. Paste this into src/index.js:

import React from 'react';
import { render } from 'react-dom';
import App from './components/App';render(<App />, document.getElementById('root'));

NOTE: If you’ve made any modifications along the way, just make sure the ID in your HTML file matches the ID we are querying here.

Now let’s create a super basic component in src/App.js:

import React from 'react';export default () => <h1>Hello, world!</h1>;

Run it!

OK, we should be kind of done now. Let’s just add a couple of scripts to our package.json file so we can easily run our app:

"start": "webpack-dev-server --mode=development",
"build": "webpack --mode=production"

Now head to your terminal, run it and see if it works!:

npm start

If all went well, you should be able to see your app at http://localhost:8080/.

Congratulations!

Well done! Now you know how to create a custom React project from scratch! 🎉 Pretty easy, right?

Next steps

At this point, I highly recommend adding your boilerplate project to GitHub so that you can clone it whenever you start a new React project, rather than going through all these steps every time (a good use case for the new repository templates feature from GitHub).

This was a very basic example to illustrate how easy it is to set up. Why not extend this further and add any other packages or configurations you commonly need in your projects? Here are some ideas:

Add more webpack loaders to handle other types of files (CSS, SASS, images, fonts etc.)
Install and configure code quality tooling such as ESLint and/or Prettier
Add dotenv and environment variables files
Split webpack config into development, production and common configs
Install and configure a testing framework, e.g. Jest, Mocha etc.

That’s it!

Thanks for reading. I hope you learned something and that you will use your newfound power to create your own boilerplate projects that you can reuse time and time again.