futureplate

a simple-ish boilerplate for

+ universal react

+ (redux-y) flux

+ react-router

+ css modules

+ code splitting

+ hot module replacement

Goals

• Simple and Clear

  • As few dependencies as possible, with a clear purpose for each.
  • Code is readable and understandable and achieves only what is outlined here in the goals, nothing more.

• Flux Architecture

  • Simple Flux implementation inspired by (and probably pretty interchangeable with) Redux.
  • Top level Store object with as many child stores as necessary.
  • Simple cache for Store data.
  • Only actions should update the stores.
  • Components interact with store via an API similar to (read: directly inspired by) react-redux:
    • store is added to props of a component via a Higher Order Component called FluxComponent.
    • Usage of React's context feature is kept as an implementation detail.
    • Entire component tree is re-rendered on store update via FluxRoot container component.

• Universal

  • App renders content on the server before client takes over.

• Routing

  • A single file defines routes for both server and client.

• Data Dependencies

  • Components express their data dependencies.

• Styles

  • CSS Modules provide modular (component-scoped classes) and reusable (composable) CSS that brings order to the global scope and explicitly ties CSS into the component hierarchy while still just being simple CSS files.
  • Preprocessors, etc. can be added easily as desired.

• Development flow and Build Process

  • All JS uses ES6 syntax via Babel.
  • Webpack provides module bundling.
  • Code splitting can be implemented on the router level.
  • Dev Mode: Re-compile bundle(s) and re-start server on any change.
  • Hot Module Replacement Mode: Optional hot reloading for React components and CSS modules.

!Goals

• Functional stores (reducers, like redux).
• Store- or component-specific re-renders (a re-render is triggered on the entire component tree on any store update).
• UI tests

Setup

requires node v4! make sure your environment is up to date

npm install

Production

npm run build

Compiles both the client and server rendering bundle in production mode with webpack. CSS is extracted into a separate static file (main.css), which is added to the index.pug template on the web server.

NOTE: ExtractTextPlugin is not run in allChunks mode by default, so CSS required by routes that are split out into separate chunks will not be extracted. That CSS is added on the client in a <style> tag, which might create a FOUC and be undesirable. Webpack is very flexible with how it handles stylesheets and a specific strategy should be implemented based on the requirements of the particular site.

npm run start

Starts the web server in production mode.

Development

npm run build:dev

Compiles assets for development with webpack in watch mode, re-compiling on any file change. CSS is loaded on the client via <style> tags (using style-loader).

npm run start:dev

Starts the web server via nodemon to re-start on any change (such as when webpack re-compiles the server-render bundle).

Hot Module Replacement

Note: This runs "vanilla webpack HMR" since most state is in the Flux store, as recommended here

npm run build:hot

Runs the build:dev script with HMR flag so it only compiles the server-render bundle (since the client bundle is handled by the webpack-dev-server).

npm run start:hot

Runs the start:dev script with HMR flag which tells the server to retrieve the client scripts from the webpack-dev-server.

npm run hot

Compiles the client bundle with hot module replacement and serves it on port 8080 via webpack-dev-server.

Core Technologies

• express for the web server.
• react for component rendering.
• react-router for universal routing.
• webpack to preprocess and bundle css and js and implement code splitting.
• babel to allow for ES2015 syntax.

Honorable Mentions

• babel
  • babel-loader to use babel in webpack.
  • babel-preset-es2015 to transform ES2015 into ES5
  • babel-preset-react to transform JSX into createElement calls.
• css processing
  • autoprefixer to add browser prefixes to CSS as needed.
  • css-loader to provide CSS modules functionality via webpack.
  • extract-text-webpack-plugin to compile all CSS into a separate file in production.
  • null-loader to ignore global CSS in the server render bundle.
  • postcss-loader to postprocess CSS in webpack.
  • postcss-import to inline @import calls in CSS.
  • style-loader to add style tags for CSS on demand in the browser.
• utility/misc
  • pug for node templates.
  • lodash for utility functions.
  • react-addons-update to implement immutable updates in the Store.
  • serialize-javascript to serialize store state and pass it safely to the client.
  • serve-favicon to serve the favicon.ico.
  • source-map-support for source map support in node.
  • superagent for client and node AJAX.
  • redial to express component data dependencies.
  • body-parser for server request body parsing (only necessary in the mock-api file).
• development
  • nodemon to restart web server in dev mode after re-compiling bundles.
  • rimraf to clean the build directory.
• hot module replacement
  • webpack-dev-server to set up hot module replacement of client assets.

Inspiration

• react-isomorphic-boilerplate
• react-router-mega-demo
• Handcrafting an isomorphic redux application with love
• book-shelf
• isomorphic500
• Backend Apps with Webpack
• react-howto
• webpack-howto
• react-transform-boilerplate
• The ultimate Webpack setup
• Welcome to Future of Web Application Delivery
• example-react-router-server-rendering-lazy-routes
• Hot Reloading in React

TODOs

• Add Testing framework (Jest) and some unit test examples.

• Use Webpack 2 when it is out of beta for tree-shaking (reference this and this).

• Routing

  • Add a way to define blocking actions on routes. i.e. actions that must complete before the route component is rendered.
  • Add a way to define error handling for route dependencies. In general, this would be for client-side 404-type situations so that a 404 page can be shown without a flicker.