Quick setup for new performance orientated, offline–first React.js applications featuring Redux, hot–reloading, PostCSS, react-router, ServiceWorker, AppCache, FontFaceObserver and Mocha.
Using react-transform-hmr, your changes in the CSS and JS get reflected in the app instantly without refreshing the page. That means that the current application state persists even when you change something in the underlying code! For a very good explanation and demo, watch Dan Abramov himself talking about it at react-europe.
Redux is a much better implementation of a flux–like, unidirectional data flow. Redux makes actions composable, reduces the boilerplate code and makes hot–reloading possible in the first place. For a good overview of redux, check out the talk linked above or the official documentation!
PostCSS is like Sass, but modular and capable of much more. PostCSS is, in essence, just a wrapper for plugins which exposes an easy to use, but very powerful API. While it is possible to replicate Sass features with PostCSS, PostCSS has an ecosystem of amazing plugins with functionalities Sass cannot even dream about having. See this talk for a short introduction to PostCSS.
Unit tests should be an important part of every web application developers toolchain. Mocha checks your application is working exactly how it should without you lifting a single finger. Congratulations, you just won a First Class ticket to world domination, fasten your seat belt please!
react-router is used for routing in this boilerplate. react-router makes routing easy to do and takes care of most of the work. (except you have to define your routes yourself) You can find the documentation right here.
ServiceWorker and AppCache make it possible to use your application offline. As soon as the website has been opened once, it is cached and available without a network connection. See this talk for an explanation of the ServiceWorker used in this boilerplate.
manifest.jsonis specifically for Chrome on Android. Users can add the website to the homescreen and use it like a native app!
Clone this repo using
git clone https://github.com/mxstbr/react-boilerplate.git.
Delete the existing git repository by running
rm -rf .git.
Initialize a new git repository with
git add .and
git commit -m "Initial commit".
npm installto install the dependencies.
npm startto start the local web server.
http://localhost:3000and you should see the app running!
Building & Deploying
npm run build, which will compile all the necessary files in a
Upload the contents of the
buildfolder to your web server.
This boilerplate includes a
.htaccess file that does two things:
Redirect all traffic to HTTPS because ServiceWorker only works for encrypted traffic
Rewrite all pages (e.g. yourdomain.com/subpage) to the
react-routertake care of presenting the correct page
The CSS modules found in the
css subfolders all get imported into one big file (
main.css), which gets transpiled with PostCSS.
css folder README for more information about the PostCSS plugins used and the CSS structure.
All files that are
required somewhere get compiled into one big file at build time. (
UglifyJS, so you don't have to worry about that.
js folder README for more information about the JS structure.
npm run serve you can start a server that's accessible in the entire local network and shows the version of the app that's in the
build folder. Useful for testing on different devices!
Unit tests live in the
test directory, and are run with
npm test. There are two files in there already, testing that the current AppActions and Reducers are working correctly. Mocha is used as a unit testing framework, check out the official documentation!
Files in the root folder
For a full explanation of all files in the root folder, see
If you simply use web fonts in your project, the page will stay blank until these fonts are downloaded. That means a lot of waiting time in which users could already read the content.
FontFaceObserver adds a
js-<font-name>-loaded class to the
body when the fonts have loaded. You should specify an initial
font-family with save fonts on the
body, and a
font-family which includes your web font. See app.js and base.css.
Adding a new font
base/_base.css, specify your initial
bodytag with only save fonts. In the
body.js-<font-name>-loadedtag, specify your
font-familystack with your web font.
<font-name>Observerfor your font.
Removing performant web font loading
Careful about removing this, as perceived performance might be highly impacted.
ServiceWorker and the
Application Cache, your application is cached for offline usage.
Cache a new file
To cache a file, add it to the
urlsToCache variable in the
Removing offline access
Careful about removing this, as there is no real downside to having your application available when the users network connection isn't perfect.
Add To Homescreen
On Chrome for Android (soon hopefully more browsers), users can add a webpage to the homescreen. Combined with offline caching, this means your web app can be used exactly like a native application.
The name and icon to be displayed are set in the
manifest.json file. Change them to your project name and icon, and try it!
Removing add to homescreen functionality
These are some things to be aware of when using this boilerplate.
Images in the HTML file(s)
<!-- Normal Image --> <img src="img/yourimg.png" /> <!-- Meta tags --> <meta property="og:image" content="img/yourimg.png" /> <!-- ... -->
Then webpack will correctly transfer the image to the build folder.
How to contribute
CONTRIBUTING.md for infos on how you can help!
This project is licensed under the MIT license, Copyright (c) 2016 Maximilian Stoiber. For more information see