Parcel React Boilerplate

We will create a simple React boilerplate with Parcel bundler, linter, prettier and a few things more for create new React apps quick.

You always can use Create React App or even a CRA version with Parcel but the scope of this guide is making a smaller/simpler boilerplate.

I recommend this approach specially for ppl who start with React because CRA does a lot of magic for us and I think it's important know which problems CRA "solves" before use it as an overkill.

If you want to skip the guide and check/fork the final result, you can do it here

Why Parcel

• Parcel doesn't require a config file at all!
• It's very fast
• Tree shaking out of the box with multicore procesing.
• Caching, Parcel do some caching after the first build so the build/rebuild times are really fast after the warmup. (welcome back to the second argument :D)

Also worth mention:

• Code splitting is out of the box in Parcel and Webpack's CRA.
• Live reload is available by default in Parcel and Webpack's CRA.

From 0 to 1

Make a new folder, and init the project:

mkdir parcel-react-boilerplate
cd parcel-react-boilerplate

yarn init -y

I will use yarn but feel free to use any package manager you want.

With yarn init -y we are creating a package.json with:

{
  "name": "parcel-react-boilerplate",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT"
}

If you follow the same folder structure of this guide, change "main": index.js for "main": "src/index.js".

Adding Parcel

First of all, let's install and configure the bundler:

yarn add react react-dom
yarn add -D parcel-bundler @babel/core @babel/preset-env @babel/preset-react

On your project root folder create a .babelrc file and add the following content:

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

Let's add a start script and a build script for starting and building our project on the package.json

"scripts": {
  "start": "parcel src/index.html"
  "build": "parcel build src/index.html"
}

Change src/index.html to the route of your main html file.

My folder structure will be

- my-project
|- src
|-- index.html
|-- index.js
|- package.json

Adding React

In index.html make sure you have imported the index.js

<script src="./index.js"></script>

We will place a div with id root to add our React content there.

<div id="root"></div>

Make sure to place this div before the index.js import. We want to load the content of the index.js on this div, for that the element must be present before index.js comes in.

For the index.js lets place some basic React code:

import React from 'react';
import { render } from 'react-dom';

const App = () => <div>Hello Wolrd!</div>;

render(<App />, document.getElementById('root'));

Adding Extras

The boilerplate is ready to go at this point, you can check it by starting the server with the script we wrote earlier.

yarn start

If everything is correct, our server will be running at http://localhost:1234 by default. The server will reload automatically when detect changes in the project without any additional configuration.

However let's add some extras to make our lifes easy. The following extras are only for develop, they will not go to the final product, for that we'll use -D on yarn.

PropTypes

Prop validation is not mandatory but it is nice to have, simple install the package:

yarn add prop-types

Autoprefixer

One thing that does CRA is autoprefixing the CSS, that means we don't need to wrote all the "alternative versions" (vendor prefixes) of the properties depending on the browser we're executing our app.

We'll use autoprefixer:

yarn add -D autoprefixer

With Parcel, we need to add a file .postcssrc to our root's project folder with the following content:

{
  "plugins": {
    "autoprefixer": {
      "grid": "autoplace"
    }
  }
}

Let's create a index.scss and import it on the index.js Parcel will install the sass module by itself.

Prettier

With Prettier we'll format our code automatically when the file is saved and we'll define rules for the entire project formatter.

yarn add -D prettier

Create the files .prettierrc and .prettierignore files on the root folder of the project:

.prettierrc

{
  "semi": true,
  "singleQuote": true,
  "useTabs": false,
  "endOfLine": "lf"
}

You can find more config options here

• semi Add a semicolon at the end of every statement.
• singleQuote Use single quotes insted of doubles JSX ignore this option.
• useTabs Ident lines with spaces.
• endOfLine End of line style of Linux/MAC and git repositories, if you share the repo with Windows users is very handy.

.prettierignore

.cache
node_modules
build
dist

ESLint

We'll add ESLint with the rules of Airbnb JavaScript Style Guide/Airbnb React/JSX Style Guide.

I use this approach because I found this rules are a good reference to follow and newcomers usually find very instructive.

yarn add -D eslint babel-eslint babel-preset-env babel-preset-react eslint-config-airbnb eslint-config-prettier eslint-plugin-import eslint-plugin-jsx-a11y eslint-plugin-prettier eslint-plugin-react

Note we're installing eslint-config-prettier and eslint-plugin-prettier for combine eslint with our exiting prettier.

In the project root folder create the files .eslinitrc and .eslintignore:

.eslintrc

{
  "extends": ["airbnb", "plugin:prettier/recommended", "prettier/react"],
  "env": {
    "browser": true,
    "commonjs": true,
    "es6": true,
    "jest": true,
    "node": true
  },
  "rules": {
    "jsx-a11y/href-no-hash": ["off"],
    "react/jsx-filename-extension": ["warn", { "extensions": [".js", ".jsx"] }]
  }
}

You can add more rules from here and set as warning or error depending your criteria.

I usually use import alphabetical order and prop types alphabetical order but I don't include in this guide because is a very personal preference.

.eslintignore

*
!*/
!*.js
!*.ts
!*.json
.cache
node_modules
dist

Git ignore

Nothing fancy, regular .gitignore for avoiding publish large and unnecesary files.

# Parcel #
.cache
dist

# Yarn / NPM #
.DS_*
*.log
logs
node_modules

# VisualStudioCode #
.history
!.vscode/tasks.json
!.vscode/launch.json

Visual Studio Code shareable config

Some VSCode config can be shared through team members. Create a .vscode folder in the project root folder, and the files extensions.json and settings.json.

extensions.json

{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode"
  ]
}

With this file, users who load the project will be prompted with extension recommendations.

settings.json

{
  "editor.formatOnSave": true
}

With this file, the file will be format on save.

Conclusion

Now you have a ready to go boilerplate for starting any React project without tons of third party libraries or configs behind the scenes also, you can add/remove any customizations you want.

What is your configuration in your React projects? There are a few things sure we can add it like TypeScript, Storybook and others, what are you recommendations?

Enjoy!

UPDATE: Now supports ES2020
UPDATE: The project now have a branch with an Electron-React boilerplate too