Redux immutable architecture boilerplate with Webpack and React

by React

reactogo

A simple Boilerplate including the best concepts and libraries of React and Redux plus some useful UI components (Toaster, Modals, Responsive Side Menu). Everything ready to build a Performant, Immutable and Responsive web application, including simple example of usage. Ideal for starting a project from scratch.

UI KIT concept explained in this article: Share your happiness and your UI KIT

Check out the live version at https://reactogo.herokuapp.com.

This boilerplate includes :

Motivations

I spent a lot of time to make these differents librairies work together. For avoiding to re-do it for every projects I'm working on, I decide to build this kickstarter, and update it as soon as needed!

Installation

Simply for this project on your local machine and then :

$ cd reacToGo
$ npm install
$ npm run start

And go to localhost:3000 in your favourite browser.
It will start the webpack-dev-server on the 3000 port and proxy all the requests to your future production server (expressjs) on the port 9000. This enable to have automatic reload on server side code update.

Also, the hot mode is set to true, i.e. you can update the style, the JSX code and the app will be updated keeping the state without reloading the page.

Environement variables

You need to set up your Firebase environment variable to have the login system. In your firebase app, you need to set up the facebook auth and put this in your variables :

 export FIREBASE_API_KEY="API KEY"
 export FIREBASE_AUTH_DOMAIN="FULL AUTH DOMAIN"
 export FIREBASE_DATABASE_URL="FULL DBB URL"

Thanks to the DefinePlugin the NODE_ENV='production' for productions build.

Features

  • Stylus: There is a default font and class in the style folder you can use
  • Images: Webpack handle the loading of all your images and files : file-loader
  • VelocityJS: Powerful animation lib to give life
  • React Router: Handle basic navigation between pages, part of the global state of the app.
  • React Motion: Physical animation lib
  • UI Kit: the /style/ui-kit.json file is included globally. You can access to the value with UI. It contain all the JS var needed to build your UI kit (breakpoints, animations, size...)
  • Media Queries: Included in the global state of the app. Accessible with functions in globals/style.js.
  • Data : Handle by Redux in a global IMMUTABLE state of the app. Check the model section underneath.
  • Firebase facebook login
  • React Modals
  • React Hot Loader: Update your react components without reload the page and keeping the main state!
  • Side Menu responsive

UI Kit and Customization

UI Kit

The UI KIT is defined is the style/ui-kit.json. It's accessible in both JS and Stylus with create only one source of truth for the UI Kit of the app :

  • JS: It's loaded with the json-loader of webpack and exposed globally via the ProvidePlugin under the name of UI. So you can simply use it for inline-style directly in the React components files without even require it:
let s = getStyle();

let MyReactComp = () => <div style={s.container}>My React Comp</div>;

function getStyle() {
  return {
    container: {
      textAlign: 'center',
      marginTop: 60,
      color: UI.lightGreen,
    },
  };
}
MyReactComp.displayName = 'MyReactComp';

export default MyReactComp;
  • STYLUS/CSS: The same file style/ui-kit.json is also loaded in the style/app.styl. So the same UI-KIT can be use also for define main app classes if needed:
.button
  padding: 10px
  box-shadow: inset 0px -2px 0px rgba(0,0,0,0.10)
  font-size: fontSM px
  display: inline-block
  border-radius: 2px
  text-align: center
  cursor: pointer

@media (min-width: breakpointT px)
  .button
    padding: 10px 20px

.button-primary
  background-color: lightGreen
  color: lightWhite
  transition: background-color 0.4s;
.button-primary:hover
  background-color: darkGreen

This way, you can both use inline-style or stylus or both at the same time without any duplication of UI-KIT and then keep the things tidy!

let s = getStyle();

let MyReactButton = () => <div style={s.container} className='button button-primary'>My React Button</div>;

function getStyle() {
  return {
    container: {
      textAlign: 'center',
      marginTop: 60,
      color: UI.lightGreen,
    },
  };
}
MyReactButton.displayName = 'MyReactButton';

export default MyReactButton;

Redux Model

Thanks to redux and its middlewares, the app state contain everything needed to modelling the UI of your app. Here is the schema of the current model (customizable of course):

  • Routing: Thanks to Redux React Router the current route and the params are hosted in the global state and handle via Action/Reducer.
  • Viewport:
    • isMobile: bool
    • isTablet: bool
    • isDesktop: bool
      Used for handle the media queries with inline css. Theses state are handled in the reducers/viewport-reducer.js reducer. Each time the window is resized, a debounced function will dispatch the action and update the state. Hence, in each components connected with React Redux will be re-render. This way, if you use the handleStyle function contained in the globals/style.js you can describe in inline css the style of your component on three differents viewports. Check the function for more informations
  • Session:
    • Token: auth token by Firebase
    • uid: User id
    • provider: facebook
    • user: User info from facebook
  • Modals:
    • isLoginModalOpen: bool
  • Side Menu:
    • isSideMenuOpen: bool
  • Toaster:
    • List of messages: []

Redux Librairies

Production

All the build scripts are in the package.json file. If you want to build locally, simply run :

$ npm run build

It will trigger the webpack.production.config.js build system and will put you everything under the dist folder.

Tests

The unit test are done with Karma Webpack and triggered after each build (or deployments). You can launch them manually via:

$ npm run test

The command is described in the package.json file. So far only the reducers functions are tested as examples. The current configuration will take all the files ending with *.spec.js and process these with Karma Webpack.

It's using Mocha for its simplicity, Expect for the assertions and PhantomJS for running those in the terminal.

The whole testing configuration is available in the /tests/karma-conf.js.

Deployment

For deploying the APP, simply push it to your CI app. I will trigger the build automatically with:

$ npm postinstall

If you are using Heroku the Procfile is already set up.

If you want to do it manually, simply copy the following command and customize it if needed:

webpack --config webpack.production.config.js

Webpack

Here's the list of the Webpack dependencies and plugins:

Contributions

Every contributions is more than welcome! Simply create a PR and I will check it asap!

GitHub

https://github.com/PBRT/reactogo