React.js Boilerplate
Quick setup for new offline–first React.js applications featuring Redux, hot–reloading, PostCSS, react-router, ServiceWorker, AppCache and Mocha.
Features
-
Using react-hot-loader, 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 funcionalities Sass cannot even dream about having.
-
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 domaination, fasten your seat belt please!
-
react-router is used for routing in this boilerplate. Using the new, and currently unreleased,
1.0
version, react-router makes routing really easy to do and takes care of a lot of the work. Since the version is not officially out yet, the documentation is not fully finished, but by far finished enough to work for most needs. -
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.
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 [email protected]:mxstbr/react-boilerplate
. -
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. -
?????? (You figure this part out)
-
Profit!
CSS
The CSS modules found in the css
subfolders all get imported into the main.css
file, which get inlined and minified into the compiled.css
file. To add/change the styling, either write the CSS into the appropriate module or make a new one and @import
it in the main.css
file at the appropriate place.
PostCSS Plugins
The boilerplate uses PostCSS, and includes a few plugins by default:
-
postcss-import
: Inlines@import
ed stylesheets to create one big stylesheet. -
postcss-simple-vars
: Makes it possible to use `$variables in your CSS. -
postcss-focus
: Adds a:focus
selector to every:hover
. -
postcss-font-magician
: Magically adds a@font-face
declaration for fonts mentioned somewhere in the CSS. For a list of supported fonts see the github page! -
autoprefixer-core
: Prefixes your CSS automatically, supporting the last two versions of all major browsers and IE 8 and up. -
cssnano
: Optimizes your CSS file. For a full list of optimizations check the offical website. -
postcss-reporter
: Makes warnings by the above plugins visible in the console.
For a full, searchable catalog of plugins go to postcss.parts.
Folder Structure
The boilerplate comes with a basic folder structure to keep the CSS files organised. This is what the folders are for:
-
base
: Global styling, e.g. setting the box–model for all elements -
components
: Component specific styling, e.g. buttons, modals,... -
layout
: Global layouts, e.g. article, homepage,... -
utils
: Utility files, e.g. variables, mixins, functions,... -
vendor
: External files, e.g. a CSS reset
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 do not have to worry about that.
Folder Structure
The folder structure of the JS files reflects how Redux works, so if you are not familiar with Redux check out the official documentation.
-
actions
: Actions get dispatched with this/these utility module(s) -
components
: The main JS folder. All your React components should be in this folder, for big projects they might be grouped into seperate subfolders. E.g. a navigation componentNav.react.js
-
constants
: Action constants need to be defined in this/these utility module(s) -
reducers
: Reducers manage the state of an app, basically a simplified implementation of Stores in Flux. For an introduction to reducers, watch this talk by @gaearon.
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. Should you be stuck and have no idea what is going on check out the official Mocha documentation!
Offline usage
To cache a file for offline use, add it to app.appcache
and to the urlsToCache
variable in the serviceworker.js
file.
License
This project is licensed under the MIT license, Copyright (c) 2015 Maximilian Stoiber. For more information see LICENSE.md
.