React.js Boilerplate
Quick setup for new performance orientated, offline–first React.js applications featuring Redux, hot–reloading, PostCSS, react-router, ServiceWorker, AppCache, FontFaceObserver and Mocha.
Made with ❤️ by Max Stoiber!
Version 3.0 is actively being developed on the v3.0.0 branch, please check it out and leave feedback!
(PRs on master
are not going to be merged.)
Features
-
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!
-
Babel is a modular JavaScript transpiler that helps to use next generation JavaScript and more, like transformation for JSX, hot loading, error catching etc. Babel has a solid ecosystem of offical preset and plugins.
-
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.json
is specifically for Chrome on Android. Users can add the website to the homescreen and use it like a native app!
Getting started
-
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 init
,git add .
andgit commit -m "Initial commit"
. -
Run
npm install
to install the dependencies. -
Run
npm start
to start the local web server. -
Go to
http://localhost:3000
and you should see the app running!
Building & Deploying
-
Run
npm run build
, which will compile all the necessary files in abuild
folder. -
Upload the contents of the
build
folder to your web server.
Server Configuration
Apache
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
index.html
to letreact-router
take care of presenting the correct page
CSS
The CSS modules found in the css
subfolders all get imported into one big file (main.css
), which gets transpiled with PostCSS.
See the css
folder README for more information about the PostCSS plugins used and the CSS structure.
JS
All files that are import
ed/require
d somewhere get compiled into one big file at build time. (build/bundle.js
) Webpack automatically optimizes your JavaScript with UglifyJS
, so you don't have to worry about that.
See the js
folder README for more information about the JS structure.
Testing
Browser testing
With 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 testing
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 docs/FILES.md
.
Opinionated features
Web Fonts
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 safe fonts on the body
, and a .js-<font-name>-loaded
font-family
which includes your web font. See app.js and base.css.
Adding a new font
-
Either add the
@font-face
declaration tobase/_fonts.css
or add a<link>
tag to theindex.html
. (Don't forget to remove the<link>
for Open Sans from theindex.html
) -
In
base/_base.css
, specify your initialfont-family
in thebody
tag with only safe fonts. In thebody.js-<font-name>-loaded
tag, specify yourfont-family
stack with your web font. -
In
js/app.js
add a<font-name>Observer
for your font.
Removing performant web font loading
Careful about removing this, as perceived performance might be highly impacted.
To remove FontFaceObserver
, don't import it in app.js
and remove it from the package.json
.
Offline access
Using a 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 serviceworker.js
file.
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.
To remove offline capability, delete serviceworker.js
, remove the import in app.js
, remove AppCachePlugin
in makewebpackconfig.js
and remove the manifest
attribute of the <html>
tag in index.html
.
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
Delete manifest.json
and remove the <link rel="manifest" href="manifest.json">
tag from the index.html
.
Gotchas
These are some things to be aware of when using this boilerplate.
Images in the HTML file(s)
Adding images to the HTML is a bit of a pain right now as webpack only goes through the JavaScript file. Add the image to your HTML file how you always would:
<!-- Normal Image -->
<img src="img/yourimg.png" />
<!-- Meta tags -->
<meta property="og:image" content="img/yourimg.png" />
<!-- ... -->
If you simply do this, webpack will not transfer the images to the build folder. To get webpack to transfer them, you have to import them with the file loader in your JavaScript somewhere, e.g.:
import 'file?name=[name].[ext]!../img/yourimg.png';
Then webpack will correctly transfer the image to the build folder.
How to contribute
See CONTRIBUTING.md
for infos on how you can help!
License
This project is licensed under the MIT license, Copyright (c) 2016 Maximilian Stoiber. For more information see LICENSE.md
.