Universal React with Rails: Part III

react on railsAugust 01, 2015by Alex Fedoseev

Building Universal app

It’s been awhile since I wrote my previous post about Rails API. Meantime a lot of things happened in JavaScript world: ES6 was officially approved and renamed to ES2015, “isomorphic” javascript (almost) became “universal”, one of the flux frameworks (which I’ve started to use in my apps) was deprecated in favour of new one (which we will use in the next post).

There is a great quote by Addy Osmani:

First do it, then do it right, then do it better.

Our goal is to learn how to build modern javascript apps and efficiently manage their state. But before do complex things, we should learn basics. So our starting point will be super simple app, which doesn’t interact with API and have only static data inside React components. In other words we will build static javascript application with server rendering using React.

:before

Here is the list of stuff you need to be familiar with to feel comfortable while reading this post:

Also take a look at these posts, we will use them later.

You can return to these links anytime, if you’ll stuck somewhere down the road.

The app

We gonna build small site with 2 pages: Main and About. Nothing special, except that it will be universal.

Source code @Github

Project structure

I always keep in mind that there can be multiple bundles in app (public site and admin area for example), so some modules will be split on two logical parts:

reusable abstraction (it will be shared between all bundles)
bundle-specific stuff.

This is how it usually looks like in my projects.


|-- /app                    <---- App container

|------ /assets             <---- Shared assets (css, fonts etc.)

|------ /bundles            <---- Bundles

|---------- /[bundle 1]

|---------- /[bundle 2]

|------ /errors             <---- Server errors layouts

|------ /libs               <---- Shared libs

|

|-- /build                  <---- Build configs

|-- /config                 <---- Application configs

|-- /public                 <---- Public assets

|-- /server                 <---- Express middlewares

|-- .dotfiles               <---- Dotfiles

|-- gulpfile.babel.js       <---- Gulpfile

|-- package.json            <---- You know what it is

|-- server.[bundle].js      <---- Bundle's Express server

|-- server.dev.js           <---- Webpack dev server

|-- server.js               <---- Reusable part for Express servers

Shared code base

Let’s start with the shared code, which will be the same on the server and on the client. Actually, it’s super simple React components with super simple react-router setup.

First of all we’ll define routes:

      
        import React      from 'react';
      
        import { Route }  from 'react-router';
      
        import App        from '../layouts/Layout';
      
        import Main       from '../components/Main';
      
        import About      from '../components/About';
      
        import NotFound   from '../components/NotFound';
      
        export default (
      
          <Route name="app" component={App}>
      
            <Route name="main"        path="/"        component={Main} />
      
            <Route name="about"       path="/about"   component={About} />
      
            <Route name="not-found"   path="*"        component={NotFound} />
      
          </Route>
      
        );

view raw routes.jsx hosted with ❤ by GitHub

And this is Layout component:

      
        /* app/bundles/app/layouts/Layout.jsx */
      
        import React    from 'react';
      
        import Header   from '../components/Header';
      
        export default class Layout extends React.Component {
      
          constructor(props, context) {
      
            super(props, context);
      
          }
      
          render() {
      
            return (
      
                <section id="layout">
      
                  <Header />
      
                  {/* In react-router 1.0.0 there is no `RouteHandler` */}
      
                  {/* It's just `this.props.children` instead */}
      
                  {this.props.children}
      
                </section>
      
            );
      
          }
      
        }

view raw Layout.jsx hosted with ❤ by GitHub

Main & About components are trivial — you can find them here.

Our main goal — make it universal. Let’s do it.

Server side rendering

Request to server (nginx isn’t shown, but it’s there)

When request from the browser gets to our app, it will be handled by Express — Node.js web app framework. Express server doesn’t know anything about React, it just takes request, parses it and passes it with response object to middleware function. This middleware takes care of the rest: initializes React app, renders initial html and sends it to browser (by response object from Express) with client’s javascript app on the board.

Express server:

      
        /* server.app.js */
      
        // This is entry point of our `app` bundle.
      
        // And here we collect bundle specific stuff 
      
        // to pass it to reusable abstraction part.
      
        // We can add `server.admin.js` bundle etc.
      
        // We gonna use ES6 / ES7 syntax in our modules
      
        // So we need to transform it to ES5 with every `require` from here on
      
        require('babel/register')({
      
          extensions: ['.js', '.jsx'],
      
          stage     : 0
      
        });
      
        // Middleware function of `app` bundle
      
        var initter = require('./app/bundles/app/initters/server');
      
        // Bundle settings
      
        var config = require('./config/server.app');
      
        // Starting express server
      
        require('./server')(initter, config);

view raw server.app.js hosted with ❤ by GitHub

      
        /* server.js */
      
        // This is shared between all bundles
      
        import express  from 'express';
      
        import parser   from 'body-parser';
      
        import cookies  from 'cookie-parser';
      
        import path     from 'path';
      
        export default (initter, config) => {
      
          // Defining some globals
      
          global.__CLIENT__ = false;
      
          global.__SERVER__ = true;
      
          global.__DEV__    = config.env !== 'production';
      
          // Initializing app
      
          const app = express();
      
          // Parsing json bodies
      
          app.use(parser.json());
      
          // Parsing urlencoded bodies
      
          app.use(parser.urlencoded({ extended: true }));
      
          // Parsing cookies
      
          app.use(cookies());
      
          // Serving static files from `public` dir
      
          app.use(express.static(path.join(__dirname, 'public')));
      
          // Here we are!
      
          // Transferring incoming requests to middleware function of the bundle
      
          app.use('/', initter);
      
          // Setting up port to listen
      
          app.set('port', config.appPort);
      
          // And listening it
      
          app.listen(app.get('port'), function() {
      
            console.log(`=> 🚀  Express ${config.bundle} ${config.env} server is running on port ${this.address().port}`);
      
          });
      
        }

view raw server.js hosted with ❤ by GitHub

Config for app bundle:

      
        /* config/server.app.js */
      
        // Importing shared config part
      
        import config from './server';
      
        // Defining name of the bundle
      
        config.bundle = 'app';
      
        // Defining port of bundle
      
        // In production we will store this in APP_PORT environment variable
      
        // In development it will be 3500
      
        config.appPort = process.env.APP_PORT || 3500;
      
        export default config;

view raw config.app.js hosted with ❤ by GitHub

      
        /* config/server.js */
      
        // This is shared between all bundles
      
        let config = {};
      
        // Defining environment
      
        config.env = process.env.NODE_ENV  || 'development';
      
        // Defining port for webpack dev server (details below)
      
        config.devPort = 3001;
      
        export default config;

view raw config.js hosted with ❤ by GitHub

Express did all the routine job and passed request to bundle’s middleware (I call it initter), where all magic is gonna happen.

Middleware function in Express is function with following signature:

function middleware(req, res, next) {
  res.send("Hello, world!")
}

This is entry point of React app, and it also will be split on abstraction / bundle-specific parts:

      
        /* app/bundles/app/initters/server.jsx */
      
        // Here we collect bundle specific stuff 
      
        // to pass it to shared initter with bundle `params`
      
        import initter    from 'app/libs/initters/server';
      
        import getAsset   from 'app/libs/getAsset';
      
        import config     from 'config/server.app';
      
        import routes     from '../routes/routes';
      
        import Head       from '../layouts/Head';
      
        export default (req, res, next) => {
      
          const { bundle } = config;
      
          const params = {
      
            // Name of the bundle
      
            bundle,
      
            // Routes
      
            routes,
      
            // <head> template
      
            Head,
      
            // Variables for Jade template
      
            // Here we store paths to compiled assets to inject them in html
      
            // Explore `getAsset` helper in `app/libs` folder
      
            locals: {
      
              jsAsset    : getAsset(bundle, 'js'),
      
              cssAsset   : getAsset(bundle, 'css'),
      
              vendorAsset: getAsset('vendor', 'js')
      
            }
      
          };
      
          // Initializing app
      
          initter(req, res, next, params);
      
        }

view raw server.app.jsx hosted with ❤ by GitHub

      
        /* app/libs/initters/server.jsx */
      
        // This initter is shared between all bundles
      
        import React      from 'react';
      
        import Router     from 'react-router';
      
        import Location   from 'react-router/lib/Location';
      
        import serialize  from 'serialize-javascript';
      
        import jade       from 'jade';
      
        export default (req, res, next, params) => {
      
          // Storing params in variables
      
          const { routes, bundle, locals, Head } = params;
      
          // Creating location object for the server router
      
          const location = new Location(req.path, req.query);
      
          // Running the router
      
          Router.run(routes, location, (error, initialState, transition) => {
      
            // If something went wrong, responding with 500
      
            if (error) return res.status(500).send(error);
      
            try {
      
              // Rendering <head> tag
      
              // Using `renderToStaticMarkup` here,
      
              // because we don't need React ids on these nodes
      
              locals.head = React.renderToStaticMarkup(
      
                <Head cssAsset={locals.cssAsset} />
      
              );
      
              // Rendering app
      
              locals.body = React.renderToString(
      
                <Router location={location} {...initialState} />
      
              );
      
              // Storing webpack chunks in variable
      
              // to expose it as global var in html for production bundles
      
              // It's related to long-term caching of assets (details below)
      
              const chunks = __DEV__ ? {} : require('public/assets/chunk-manifest.json');
      
              locals.chunks = serialize(chunks);
      
              // Defining path to jade layout
      
              const layout = `${process.cwd()}/app/bundles/${bundle}/layouts/Layout.jade`;
      
              // Compiling initial html
      
              const html = jade.compileFile(layout, { pretty: false })(locals);
      
              // 😽💨
      
              res.send(html);
      
            } catch (err) {
      
              // If something went wrong, responding with 500
      
              res.status(500).send(err.stack);
      
            }
      
          });
      
        }

view raw server.jsx hosted with ❤ by GitHub

Jade template is pretty straightforward:

      
        doctype html
      
        html
      
          // Injecting `locals.head`
      
          != head
      
          body
      
            // Injecting `locals.body`
      
            #app!= body
      
            // Injecting `locals.chunks` global for webpack
      
            script.
      
              window.__CHUNKS__ = !{chunks};
      
            // Injecting js assets
      
            script(src="#{vendorAsset}")
      
            script(src="#{jsAsset}")

view raw Layout.jade hosted with ❤ by GitHub

At this point initial html was rendered and sent to browser with client’s javascript app.

Client entry point

Client’s initter is much easier.

      
        /* app/bundles/app/initters/client.jsx */
      
        // Here we collect bundle specific stuff, same as for server
      
        // Babel polyfill, required for some of the ES6/ES7 features
      
        import polyfill   from 'babel/polyfill';
      
        import initter    from 'app/libs/initters/client';
      
        import routes     from '../routes/routes';
      
        const params = { routes };
      
        export default initter(params);

view raw client.app.jsx hosted with ❤ by GitHub

      
        /* app/libs/initters/client.jsx */
      
        // This initter is shared between all bundles
      
        import React            from 'react';
      
        import Router           from 'react-router';
      
        import BrowserHistory   from 'react-router/lib/BrowserHistory';
      
        export default (params) => {
      
          const { routes } = params;
      
          // Creating history object for the client router
      
          const history = new BrowserHistory();
      
          // Creating app container
      
          const AppContainer = (
      
            <Router history={history} children={routes} />
      
          );
      
          // Selecting DOM container for app
      
          const appDOMNode = document.getElementById('app');
      
          // Flushing application to DOM
      
          React.render(AppContainer, appDOMNode);
      
        }

view raw client.jsx hosted with ❤ by GitHub

Next thing we need to learn is how to build the client bundles and how to setup production / development environments with gulp & webpack.

Gulp, Webpack & hot reloading

Building process is the biggest pain in the ass in javascript world, so get ready. We’re gonna setup two different environments: development & production. In the end there will be available 3 console commands:

npm start or gulp start:dev
Runs development web server with hot reloading.
npm run prod or gulp start:prod
Runs local server with production ready bundles to check how it works.
npm run build or just gulp
Compiles production builds.

Key tools we’re gonna use are Gulp and Webpack. Here is the gulpfile:

      
        /* gulpfile.babel.js */
      
        import gulp         from 'gulp';
      
        import webpack      from 'webpack';
      
        import eslint       from 'eslint/lib/cli';
      
        import run          from 'run-sequence';
      
        import gutil        from 'gulp-util';
      
        import { exec }     from 'child_process';
      
        import del          from 'del';
      
        import gulpConfig   from './build/gulp.config';
      
        // Task name to compile production assets
      
        const prodBuildTask = 'build';
      
        // Task name to start dev server
      
        const startDevTask = 'start:dev';
      
        // Task name to start local server with production assets
      
        const startProdTask = 'start:prod';
      
        // Defining environment
      
        const isDevBuild = process.argv.indexOf(startDevTask) !== -1;
      
        // Defining default task
      
        const startTask = isDevBuild ? startDevTask : prodBuildTask;
      
        // Importing gulp config (it's function, returns an object)
      
        const config = gulpConfig(isDevBuild);
      
        /* Run tasks */
      
        // Using `run-sequence` plugin to group [async tasks] in [sync groups of async tasks]
      
        // 1 group: Cleaning public folder and linting scripts
      
        // 2 group: Compiling assets and coping static stuff (fonts, favicon etc.) to public folder
      
        // 3 group: Starting local Express servers
      
        gulp.task('default', [startTask]);
      
        gulp.task(prodBuildTask, done => {
      
          run(['clean', 'lint'], ['bundle', 'copy'], done);
      
        });
      
        gulp.task(startDevTask, done => {
      
          run(['clean', 'lint'], ['bundle', 'copy'], ['server'], done);
      
        });
      
        gulp.task(startProdTask, done => {
      
          run(['clean', 'lint'], ['bundle', 'copy'], ['server'], done);
      
        });
      
        /* Node servers starter */
      
        // Helper to start Express servers from gulp
      
        const startServer = (serverPath, done) => {
      
          // Defining production environment variable
      
          const prodFlag = !isDevBuild ? 'NODE_ENV=production' : '';
      
          // Starting the server
      
          const server = exec(`NODE_PATH=. ${prodFlag} node ${serverPath}`);
      
          // Handling messages from server
      
          server.stdout.on('data', data => {
      
            // Checking if it's a message from webpack dev server 
      
            // that initial compile is finished
      
            if (done && data === 'Webpack: Done!') {
      
              // Notifying gulp that assets are compiled, this task is done
      
              done();
      
            } else {
      
              // Just printing output from server to console
      
              gutil.log(data.trim());
      
            }
      
          });
      
          // If there is an error - printing output to console and doing the BEEP
      
          server.stderr.on('data', data => {
      
            gutil.log(gutil.colors.red(data.trim()));
      
            gutil.beep();
      
          });
      
        };
      
        /* Build bundles */
      
        gulp.task('bundle', done => {
      
          if (isDevBuild) {
      
            // Starting webpack dev server
      
            startServer('server.dev.js', done);
      
          } else {
      
            // Just compiling assets
      
            webpack(config.webpack).run(done);
      
          }
      
        });
      
        /* Start express servers */
      
        gulp.task('server', done => {
      
          const servers = config.server.paths;
      
          let queue     = servers.length;
      
          servers.forEach(server => {
      
            startServer(server);
      
            if (--queue === 0) done();
      
          });
      
        });
      
        /* Copy files to `public` */
      
        gulp.task('copy', done => {
      
          const files = config.copy.files;
      
          let   queue = files.length;
      
          files.forEach(file => {
      
            const from = config.copy.from + file[0];
      
            const to   = config.copy.to + (file[1] || file[0]);
      
            exec(`cp -R ${from} ${to}`, err => {
      
              if (err) {
      
                gutil.log(gutil.colors.red(err));
      
                gutil.beep();
      
              }
      
              if (--queue === 0) done();
      
            });
      
          });
      
        });
      
        /* Lint scripts */
      
        gulp.task('lint', done => {
      
          eslint.execute('--ext .js,.jsx .');
      
          done();
      
        });
      
        /* Clean up public before build */
      
        gulp.task('clean', done => {
      
          del(['./public/**/*'], done);
      
        });

view raw gulpfile.babel.js hosted with ❤ by GitHub

      
        /* build/gulp.config.js */
      
        import webpackDevConfig   from './webpack.config.dev';
      
        import webpackProdConfig  from './webpack.config.prod';
      
        const _app    = './app';
      
        const _public = './public';
      
        const _assets = `${_app}/assets`;
      
        export default (isDevBuild) => {
      
          return {
      
            webpack: isDevBuild ? webpackDevConfig : webpackProdConfig,
      
            server: {
      
              paths: ['./server.app.js']
      
            },
      
            copy: {
      
              from : _assets,
      
              files: [
      
                [ '/tinies/favicon.ico', '/' ],
      
                [ '/tinies/robots.txt',  '/' ]
      
              ],
      
              to: _public
      
            }
      
          };
      
        }

view raw gulpfile.config.js hosted with ❤ by GitHub

For each environment there will be its own setup.

Production

First let’s define requirements for production build:

Asset name should contain identifier for long-term caching purposes. We should include hash of the asset file in URL, thus when we’ll update the app, visitor’s browser will download updated asset, rather than using old one from cache. More detailed explanation on subject — in this medium post.
Our app and vendor’s modules should be split in separated chunks. Every time we update the app, whole client’s asset is changed. So visitor have to re-download it, incl. vendor’s modules, that hasn’t been changed. If we will split client’s bundle in two chunks — app and vendor’s stuff — users won’t need to re-download vendor’s modules, because it’s in different chunk and vendor’s chunk is cached by the browser.
CSS asset should be extracted out of javascript bundle and placed in head tag above initial html. If we won’t do this, visitors will see un-styled content for a moment, because initial html from server is placed above the javascript assets. You will notice this in development mode.
Assets files should be minified & gzipped. So we will be serving smaller-sized assets to client.

For webpack compiler we have file with 2 end points:

      
        /* build/bundles/app.js */
      
        import scripts  from '../../app/bundles/app/initters/client.jsx';
      
        import styles   from '../../app/bundles/app/layouts/Layout.styl';

view raw app.js hosted with ❤ by GitHub

Here is webpack production config:

      
        /* build/webpack.config.prod.js */
      
        import webpack        from 'webpack';
      
        import Extract        from 'extract-text-webpack-plugin';
      
        import Gzip           from 'compression-webpack-plugin';
      
        import Manifest       from 'webpack-manifest-plugin';
      
        import ChunkManifest  from 'chunk-manifest-webpack-plugin';
      
        import path           from 'path';
      
        export default {
      
          // Defining entry point
      
          entry: {
      
            // Bundle's entry points
      
            app: './build/bundles/app.js',
      
            // List of vendor's modules
      
            // To extract them to separate chunk
      
            vendor: ['react', 'react-router']
      
          },
      
          // Defining output params
      
          output: {
      
            path         : './public/assets',
      
            filename     : '[name]-[chunkhash].js',
      
            chunkFilename: '[name]-[chunkhash].js'
      
          },
      
          // Defining resolver params
      
          // On the server we use NODE_PATH=.
      
          // On the client we use resolve.alias
      
          resolve: {
      
            alias: {
      
              'app'   : path.join(process.cwd(), 'app'),
      
              'config': path.join(process.cwd(), 'config'),
      
              'public': path.join(process.cwd(), 'public')
      
            },
      
            extensions: ['', '.js', '.jsx']
      
          },
      
          devtool : false,
      
          debug   : false,
      
          progress: true,
      
          node    : {
      
            fs: 'empty'
      
          },
      
          plugins: [
      
            // Extracting css
      
            new Extract('[name]-[chunkhash].css'),
      
            // Extracting vendor libs to separate chunk
      
            new webpack.optimize.CommonsChunkPlugin({
      
              name     : 'vendor',
      
              chunks   : ['app'],
      
              filename : 'vendor-[chunkhash].js',
      
              minChunks: Infinity
      
            }),
      
            // Defining some globals
      
            new webpack.DefinePlugin({
      
              __CLIENT__   : true,
      
              __SERVER__   : false,
      
              __DEV__      : false,
      
              __DEVTOOLS__ : false,
      
              'process.env': {
      
                'NODE_ENV': JSON.stringify('production')
      
              }
      
            }),
      
            // Avoiding modules duplication
      
            new webpack.optimize.DedupePlugin(),
      
            // Extracting chunks filenames to json file
      
            // Required to resolve assets filenames with hashes on server
      
            // See `getAsset` helper in `app/libs/getAsset.js`
      
            new Manifest(),
      
            // Extracting chunks internal ids to json file
      
            // Required to keep vendor's chunkhash unchanged
      
            new ChunkManifest({
      
              filename        : 'chunk-manifest.json',
      
              manifestVariable: '__CHUNKS__'
      
            }),
      
            // Also required to keep vendor's chunkhash unchanged
      
            new webpack.optimize.OccurenceOrderPlugin(),
      
            // Minifying js assets
      
            new webpack.optimize.UglifyJsPlugin({
      
              compress: {
      
                'warnings'     : false,
      
                'drop_debugger': true,
      
                'drop_console' : true,
      
                'pure_funcs'   : ['console.log']
      
              }
      
            }),
      
            // Gzipping assets
      
            new Gzip({
      
              asset    : '{file}.gz',
      
              algorithm: 'gzip',
      
              regExp   : /\.js$|\.css$/
      
            })
      
          ],
      
          // Defining loaders
      
          module: {
      
            noParse: /\.min\.js$/,
      
            loaders: [
      
              { test  : /\.jsx?$/, loader: 'babel?stage=0',  exclude: /node_modules/ },
      
              {
      
                test  : /\.styl$/,
      
                loader: Extract.extract('style', 'css!autoprefixer?{browsers:["last 2 version"], cascade:false}!stylus')
      
              },
      
              {
      
                test  : /\.css$/,
      
                loader: Extract.extract('style', 'css!autoprefixer?{browsers:["last 2 version"], cascade:false}')
      
              }
      
            ]
      
          }
      
        }

view raw webpack.config.prod.js hosted with ❤ by GitHub

npm run prod and we have compiled assets in _public/assets_ folder ready to deploy.

Development

Requirements for development build:

Local dev server should be hot reloadable. Webpage should automatically reflect all changes in js / css files on file save.

We don’t care about long-term caching, css extraction and assets minification in dev environment.

Hot reloadable dev server

The main idea of hot reloadable dev server, is that webpack is starting his own express server on some port (devPort in our config) and serving all assets from there with polling script on top:

<script src="[http://lvh.me:3001/assets/app.js](http://lvh.me:3001/assets/app.js)"></script>

Under the hood it observes the assets files, if it’s changed, it recompiles assets and sends changes to client. So you don’t need to reload page on every change. Here is how to set this up for React application:

      
        /* build/webpack.config.dev.js */
      
        import webpack      from 'webpack';
      
        import path         from 'path';
      
        import appConfig    from '../config/server.app';
      
        export default {
      
          // Defining entry points for webpack dev server
      
          entry: {
      
            app: [
      
              `webpack-dev-server/client?http://lvh.me:${appConfig.devPort}`,
      
              'webpack/hot/only-dev-server',
      
              './build/bundles/app.js'
      
            ],
      
            vendor: ['react', 'react-router']
      
          },
      
          // Defining output for webpack dev server
      
          output: {
      
            path      : path.join(process.cwd(), 'public', 'assets'),
      
            filename  : '[name].js',
      
            publicPath: `http://lvh.me:${appConfig.devPort}/assets`
      
          },
      
          resolve: {
      
            alias: {
      
              'app'   : path.join(process.cwd(), 'app'),
      
              'config': path.join(process.cwd(), 'config'),
      
              'public': path.join(process.cwd(), 'public')
      
            },
      
            extensions: ['', '.js', '.jsx']
      
          },
      
          // Source maps are slow, eval is fast
      
          devtool : '#eval',
      
          debug   : true,
      
          progress: true,
      
          node    : {
      
            fs: 'empty'
      
          },
      
          plugins: [
      
            // Enabling dev server
      
            new webpack.HotModuleReplacementPlugin(),
      
            // Don't update if there was error
      
            new webpack.NoErrorsPlugin(),
      
            new webpack.optimize.CommonsChunkPlugin({
      
              name     : 'vendor',
      
              chunks   : ['app'],
      
              filename : 'vendor.js',
      
              minChunks: Infinity
      
            }),
      
            new webpack.DefinePlugin({
      
              __CLIENT__   : true,
      
              __SERVER__   : false,
      
              __DEV__      : true,
      
              __DEVTOOLS__ : true,
      
              'process.env': {
      
                'NODE_ENV': JSON.stringify('development')
      
              }
      
            })
      
          ],
      
          module: {
      
            noParse: /\.min\.js$/,
      
            loaders: [
      
              // Notice `react-hot` loader, required for React components hot reloading
      
              { test  : /\.jsx?$/, loaders: ['react-hot', 'babel?stage=0'],  exclude: /node_modules/ },
      
              {
      
                test  : /\.styl$/,
      
                loader: 'style!css!autoprefixer?{browsers:["last 2 version"], cascade:false}!stylus'
      
              },
      
              {
      
                test  : /\.css$/,
      
                loader: 'style!css!autoprefixer?{browsers:["last 2 version"], cascade:false}'
      
              }
      
            ]
      
          }
      
        }

view raw webpack.config.dev.js hosted with ❤ by GitHub

And here is webpack development server, which we start by npm start (before express server of our app):

      
        /* server.dev.js */
      
        require('babel/register')({
      
          extensions: ['.js', '.jsx'],
      
          stage     : 0
      
        });
      
        var webpack          = require('webpack');
      
        var WebpackDevServer = require('webpack-dev-server');
      
        var webpackConfig    = require('./build/webpack.config.dev');
      
        var serverConfig     = require('./config/server');
      
        var initialCompile = true;
      
        var compiler = webpack(webpackConfig);
      
        var devServer = new WebpackDevServer(compiler, {
      
          contentBase       : 'http://lvh.me:' + serverConfig.devPort,
      
          publicPath        : webpackConfig.output.publicPath,
      
          hot               : true,
      
          inline            : true,
      
          historyApiFallback: true,
      
          quiet             : false,
      
          noInfo            : false,
      
          lazy              : false,
      
          stats             : {
      
            colors  : true,
      
            hash    : false,
      
            version : false,
      
            chunks  : false,
      
            children: false
      
          }
      
        });
      
        devServer.listen(serverConfig.devPort, 'localhost', function(err) {
      
          if (err) console.error(err);
      
          console.log('=> 🔥  Webpack development server is running on port %s', serverConfig.devPort);
      
        });
      
        // This part will notify gulp that assets are compiled
      
        // Gulp will start application Express server then
      
        // (and it'll pick up assets filenames from json manifest to inject them in html)
      
        compiler.plugin('done', function() {
      
          if (initialCompile) {
      
            initialCompile = false;
      
            process.stdout.write('Webpack: Done!');
      
          }
      
        });

view raw server.dev.js hosted with ❤ by GitHub

Now we can run npm start and open http://lvh.me in browser. Every time we make a changes in js or css files, page will be automatically updated by webpack dev server.

Conclusion

We’ve learned how to build simple universal javascript app using React (Dude! It’s not simple at all!). But this is only beginning. Real-world apps is much more complex, so here is the questions we have to answer next:

How to manage state in our app?
How to prefetch data on the server, so we can render html with data from API and serve it to client?
How to secure it?
How to deploy it to production server?

Stay tuned to get the answers!

Part I: Planning the application
Part II: Building JSON API
Part III: Building Universal app
Part IV: Making Universal Flux app

Alex Fedoseev

Lead Developer at ShakaCode

Share this article

Are you looking for a software development partner who can

develop modern, high-performance web apps and sites?

See what we've done

	import React from 'react';
	import { Route } from 'react-router';

	import App from '../layouts/Layout';
	import Main from '../components/Main';
	import About from '../components/About';
	import NotFound from '../components/NotFound';


	export default (

	<Route name="app" component={App}>

	<Route name="main" path="/" component={Main} />
	<Route name="about" path="/about" component={About} />

	<Route name="not-found" path="*" component={NotFound} />

	</Route>

	);

	/* app/bundles/app/layouts/Layout.jsx */

	import React from 'react';

	import Header from '../components/Header';


	export default class Layout extends React.Component {


	constructor(props, context) {
	super(props, context);
	}


	render() {

	return (
	<section id="layout">
	<Header />
	{/* In react-router 1.0.0 there is no `RouteHandler` */}
	{/* It's just `this.props.children` instead */}
	{this.props.children}
	</section>
	);

	}


	}

	/* server.app.js */

	// This is entry point of our `app` bundle.
	// And here we collect bundle specific stuff
	// to pass it to reusable abstraction part.
	// We can add `server.admin.js` bundle etc.


	// We gonna use ES6 / ES7 syntax in our modules
	// So we need to transform it to ES5 with every `require` from here on
	require('babel/register')({
	extensions: ['.js', '.jsx'],
	stage : 0
	});

	// Middleware function of `app` bundle
	var initter = require('./app/bundles/app/initters/server');

	// Bundle settings
	var config = require('./config/server.app');

	// Starting express server
	require('./server')(initter, config);

	/* server.js */

	// This is shared between all bundles

	import express from 'express';
	import parser from 'body-parser';
	import cookies from 'cookie-parser';
	import path from 'path';


	export default (initter, config) => {

	// Defining some globals
	global.__CLIENT__ = false;
	global.__SERVER__ = true;
	global.__DEV__ = config.env !== 'production';

	// Initializing app
	const app = express();

	// Parsing json bodies
	app.use(parser.json());

	// Parsing urlencoded bodies
	app.use(parser.urlencoded({ extended: true }));

	// Parsing cookies
	app.use(cookies());

	// Serving static files from `public` dir
	app.use(express.static(path.join(__dirname, 'public')));

	// Here we are!
	// Transferring incoming requests to middleware function of the bundle
	app.use('/', initter);

	// Setting up port to listen
	app.set('port', config.appPort);

	// And listening it
	app.listen(app.get('port'), function() {
	console.log(`=> 🚀 Express ${config.bundle} ${config.env} server is running on port ${this.address().port}`);
	});

	}

	/* config/server.app.js */

	// Importing shared config part
	import config from './server';

	// Defining name of the bundle
	config.bundle = 'app';

	// Defining port of bundle
	// In production we will store this in APP_PORT environment variable
	// In development it will be 3500
	config.appPort = process.env.APP_PORT \|\| 3500;

	export default config;

	/* config/server.js */

	// This is shared between all bundles

	let config = {};

	// Defining environment
	config.env = process.env.NODE_ENV \|\| 'development';

	// Defining port for webpack dev server (details below)
	config.devPort = 3001;

	export default config;

	/* app/bundles/app/initters/server.jsx */

	// Here we collect bundle specific stuff
	// to pass it to shared initter with bundle `params`

	import initter from 'app/libs/initters/server';
	import getAsset from 'app/libs/getAsset';
	import config from 'config/server.app';
	import routes from '../routes/routes';
	import Head from '../layouts/Head';


	export default (req, res, next) => {

	const { bundle } = config;

	const params = {

	// Name of the bundle
	bundle,

	// Routes
	routes,

	// <head> template
	Head,

	// Variables for Jade template
	// Here we store paths to compiled assets to inject them in html
	// Explore `getAsset` helper in `app/libs` folder
	locals: {

	jsAsset : getAsset(bundle, 'js'),
	cssAsset : getAsset(bundle, 'css'),
	vendorAsset: getAsset('vendor', 'js')

	}

	};

	// Initializing app
	initter(req, res, next, params);

	}

	/* app/libs/initters/server.jsx */

	// This initter is shared between all bundles

	import React from 'react';
	import Router from 'react-router';
	import Location from 'react-router/lib/Location';
	import serialize from 'serialize-javascript';
	import jade from 'jade';


	export default (req, res, next, params) => {

	// Storing params in variables
	const { routes, bundle, locals, Head } = params;

	// Creating location object for the server router
	const location = new Location(req.path, req.query);

	// Running the router
	Router.run(routes, location, (error, initialState, transition) => {

	// If something went wrong, responding with 500
	if (error) return res.status(500).send(error);

	try {

	// Rendering <head> tag
	// Using `renderToStaticMarkup` here,
	// because we don't need React ids on these nodes
	locals.head = React.renderToStaticMarkup(
	<Head cssAsset={locals.cssAsset} />
	);

	// Rendering app
	locals.body = React.renderToString(
	<Router location={location} {...initialState} />
	);

	// Storing webpack chunks in variable
	// to expose it as global var in html for production bundles
	// It's related to long-term caching of assets (details below)
	const chunks = __DEV__ ? {} : require('public/assets/chunk-manifest.json');

	locals.chunks = serialize(chunks);

	// Defining path to jade layout
	const layout = `${process.cwd()}/app/bundles/${bundle}/layouts/Layout.jade`;

	// Compiling initial html
	const html = jade.compileFile(layout, { pretty: false })(locals);

	// 😽💨
	res.send(html);

	} catch (err) {

	// If something went wrong, responding with 500
	res.status(500).send(err.stack);

	}

	});

	}

	doctype html
	html

	// Injecting `locals.head`
	!= head

	body

	// Injecting `locals.body`
	#app!= body

	// Injecting `locals.chunks` global for webpack
	script.
	window.__CHUNKS__ = !{chunks};

	// Injecting js assets
	script(src="#{vendorAsset}")
	script(src="#{jsAsset}")

	/* app/bundles/app/initters/client.jsx */

	// Here we collect bundle specific stuff, same as for server

	// Babel polyfill, required for some of the ES6/ES7 features
	import polyfill from 'babel/polyfill';

	import initter from 'app/libs/initters/client';
	import routes from '../routes/routes';


	const params = { routes };

	export default initter(params);

	/* app/libs/initters/client.jsx */

	// This initter is shared between all bundles

	import React from 'react';
	import Router from 'react-router';
	import BrowserHistory from 'react-router/lib/BrowserHistory';


	export default (params) => {

	const { routes } = params;

	// Creating history object for the client router
	const history = new BrowserHistory();

	// Creating app container
	const AppContainer = (
	<Router history={history} children={routes} />
	);

	// Selecting DOM container for app
	const appDOMNode = document.getElementById('app');

	// Flushing application to DOM
	React.render(AppContainer, appDOMNode);

	}

	/* gulpfile.babel.js */

	import gulp from 'gulp';
	import webpack from 'webpack';
	import eslint from 'eslint/lib/cli';
	import run from 'run-sequence';
	import gutil from 'gulp-util';
	import { exec } from 'child_process';
	import del from 'del';

	import gulpConfig from './build/gulp.config';


	// Task name to compile production assets
	const prodBuildTask = 'build';

	// Task name to start dev server
	const startDevTask = 'start:dev';

	// Task name to start local server with production assets
	const startProdTask = 'start:prod';

	// Defining environment
	const isDevBuild = process.argv.indexOf(startDevTask) !== -1;

	// Defining default task
	const startTask = isDevBuild ? startDevTask : prodBuildTask;

	// Importing gulp config (it's function, returns an object)
	const config = gulpConfig(isDevBuild);


	/* Run tasks */

	// Using `run-sequence` plugin to group [async tasks] in [sync groups of async tasks]
	// 1 group: Cleaning public folder and linting scripts
	// 2 group: Compiling assets and coping static stuff (fonts, favicon etc.) to public folder
	// 3 group: Starting local Express servers

	gulp.task('default', [startTask]);

	gulp.task(prodBuildTask, done => {
	run(['clean', 'lint'], ['bundle', 'copy'], done);
	});

	gulp.task(startDevTask, done => {
	run(['clean', 'lint'], ['bundle', 'copy'], ['server'], done);
	});

	gulp.task(startProdTask, done => {
	run(['clean', 'lint'], ['bundle', 'copy'], ['server'], done);
	});



	/* Node servers starter */

	// Helper to start Express servers from gulp
	const startServer = (serverPath, done) => {

	// Defining production environment variable
	const prodFlag = !isDevBuild ? 'NODE_ENV=production' : '';

	// Starting the server
	const server = exec(`NODE_PATH=. ${prodFlag} node ${serverPath}`);

	// Handling messages from server
	server.stdout.on('data', data => {

	// Checking if it's a message from webpack dev server
	// that initial compile is finished
	if (done && data === 'Webpack: Done!') {
	// Notifying gulp that assets are compiled, this task is done
	done();
	} else {
	// Just printing output from server to console
	gutil.log(data.trim());
	}
	});

	// If there is an error - printing output to console and doing the BEEP
	server.stderr.on('data', data => {
	gutil.log(gutil.colors.red(data.trim()));
	gutil.beep();
	});

	};



	/* Build bundles */

	gulp.task('bundle', done => {

	if (isDevBuild) {

	// Starting webpack dev server
	startServer('server.dev.js', done);

	} else {

	// Just compiling assets
	webpack(config.webpack).run(done);

	}

	});



	/* Start express servers */

	gulp.task('server', done => {

	const servers = config.server.paths;
	let queue = servers.length;

	servers.forEach(server => {
	startServer(server);
	if (--queue === 0) done();
	});

	});



	/* Copy files to `public` */

	gulp.task('copy', done => {

	const files = config.copy.files;
	let queue = files.length;

	files.forEach(file => {
	const from = config.copy.from + file[0];
	const to = config.copy.to + (file[1] \|\| file[0]);
	exec(`cp -R ${from} ${to}`, err => {
	if (err) {
	gutil.log(gutil.colors.red(err));
	gutil.beep();
	}
	if (--queue === 0) done();
	});
	});

	});



	/* Lint scripts */

	gulp.task('lint', done => {

	eslint.execute('--ext .js,.jsx .');
	done();

	});



	/* Clean up public before build */

	gulp.task('clean', done => {

	del(['./public/*/'], done);

	});

	/* build/gulp.config.js */

	import webpackDevConfig from './webpack.config.dev';
	import webpackProdConfig from './webpack.config.prod';


	const _app = './app';
	const _public = './public';
	const _assets = `${_app}/assets`;


	export default (isDevBuild) => {

	return {

	webpack: isDevBuild ? webpackDevConfig : webpackProdConfig,

	server: {
	paths: ['./server.app.js']
	},

	copy: {
	from : _assets,
	files: [
	[ '/tinies/favicon.ico', '/' ],
	[ '/tinies/robots.txt', '/' ]
	],
	to: _public
	}

	};

	}

	/* build/bundles/app.js */

	import scripts from '../../app/bundles/app/initters/client.jsx';
	import styles from '../../app/bundles/app/layouts/Layout.styl';

	/* build/webpack.config.prod.js */

	import webpack from 'webpack';
	import Extract from 'extract-text-webpack-plugin';
	import Gzip from 'compression-webpack-plugin';
	import Manifest from 'webpack-manifest-plugin';
	import ChunkManifest from 'chunk-manifest-webpack-plugin';
	import path from 'path';


	export default {

	// Defining entry point
	entry: {

	// Bundle's entry points
	app: './build/bundles/app.js',

	// List of vendor's modules
	// To extract them to separate chunk
	vendor: ['react', 'react-router']

	},

	// Defining output params
	output: {
	path : './public/assets',
	filename : '[name]-[chunkhash].js',
	chunkFilename: '[name]-[chunkhash].js'
	},

	// Defining resolver params
	// On the server we use NODE_PATH=.
	// On the client we use resolve.alias
	resolve: {
	alias: {
	'app' : path.join(process.cwd(), 'app'),
	'config': path.join(process.cwd(), 'config'),
	'public': path.join(process.cwd(), 'public')
	},
	extensions: ['', '.js', '.jsx']
	},

	devtool : false,
	debug : false,
	progress: true,
	node : {
	fs: 'empty'
	},

	plugins: [

	// Extracting css
	new Extract('[name]-[chunkhash].css'),

	// Extracting vendor libs to separate chunk
	new webpack.optimize.CommonsChunkPlugin({
	name : 'vendor',
	chunks : ['app'],
	filename : 'vendor-[chunkhash].js',
	minChunks: Infinity
	}),

	// Defining some globals
	new webpack.DefinePlugin({
	__CLIENT__ : true,
	__SERVER__ : false,
	__DEV__ : false,
	__DEVTOOLS__ : false,
	'process.env': {
	'NODE_ENV': JSON.stringify('production')
	}
	}),

	// Avoiding modules duplication
	new webpack.optimize.DedupePlugin(),

	// Extracting chunks filenames to json file
	// Required to resolve assets filenames with hashes on server
	// See `getAsset` helper in `app/libs/getAsset.js`
	new Manifest(),

	// Extracting chunks internal ids to json file
	// Required to keep vendor's chunkhash unchanged
	new ChunkManifest({
	filename : 'chunk-manifest.json',
	manifestVariable: '__CHUNKS__'
	}),

	// Also required to keep vendor's chunkhash unchanged
	new webpack.optimize.OccurenceOrderPlugin(),

	// Minifying js assets
	new webpack.optimize.UglifyJsPlugin({
	compress: {
	'warnings' : false,
	'drop_debugger': true,
	'drop_console' : true,
	'pure_funcs' : ['console.log']
	}
	}),

	// Gzipping assets
	new Gzip({
	asset : '{file}.gz',
	algorithm: 'gzip',
	regExp : /\.js$\|\.css$/
	})
	],

	// Defining loaders
	module: {
	noParse: /\.min\.js$/,
	loaders: [
	{ test : /\.jsx?$/, loader: 'babel?stage=0', exclude: /node_modules/ },
	{
	test : /\.styl$/,
	loader: Extract.extract('style', 'css!autoprefixer?{browsers:["last 2 version"], cascade:false}!stylus')
	},
	{
	test : /\.css$/,
	loader: Extract.extract('style', 'css!autoprefixer?{browsers:["last 2 version"], cascade:false}')
	}
	]
	}


	}

	/* build/webpack.config.dev.js */

	import webpack from 'webpack';
	import path from 'path';

	import appConfig from '../config/server.app';


	export default {

	// Defining entry points for webpack dev server
	entry: {
	app: [
	`webpack-dev-server/client?http://lvh.me:${appConfig.devPort}`,
	'webpack/hot/only-dev-server',
	'./build/bundles/app.js'
	],
	vendor: ['react', 'react-router']
	},

	// Defining output for webpack dev server
	output: {
	path : path.join(process.cwd(), 'public', 'assets'),
	filename : '[name].js',
	publicPath: `http://lvh.me:${appConfig.devPort}/assets`
	},

	resolve: {
	alias: {
	'app' : path.join(process.cwd(), 'app'),
	'config': path.join(process.cwd(), 'config'),
	'public': path.join(process.cwd(), 'public')
	},
	extensions: ['', '.js', '.jsx']
	},

	// Source maps are slow, eval is fast
	devtool : '#eval',
	debug : true,
	progress: true,
	node : {
	fs: 'empty'
	},

	plugins: [

	// Enabling dev server
	new webpack.HotModuleReplacementPlugin(),

	// Don't update if there was error
	new webpack.NoErrorsPlugin(),

	new webpack.optimize.CommonsChunkPlugin({
	name : 'vendor',
	chunks : ['app'],
	filename : 'vendor.js',
	minChunks: Infinity
	}),

	new webpack.DefinePlugin({
	__CLIENT__ : true,
	__SERVER__ : false,
	__DEV__ : true,
	__DEVTOOLS__ : true,
	'process.env': {
	'NODE_ENV': JSON.stringify('development')
	}
	})
	],

	module: {
	noParse: /\.min\.js$/,
	loaders: [

	// Notice `react-hot` loader, required for React components hot reloading
	{ test : /\.jsx?$/, loaders: ['react-hot', 'babel?stage=0'], exclude: /node_modules/ },
	{
	test : /\.styl$/,
	loader: 'style!css!autoprefixer?{browsers:["last 2 version"], cascade:false}!stylus'
	},
	{
	test : /\.css$/,
	loader: 'style!css!autoprefixer?{browsers:["last 2 version"], cascade:false}'
	}
	]
	}


	}

	/* server.dev.js */

	require('babel/register')({
	extensions: ['.js', '.jsx'],
	stage : 0
	});

	var webpack = require('webpack');
	var WebpackDevServer = require('webpack-dev-server');
	var webpackConfig = require('./build/webpack.config.dev');
	var serverConfig = require('./config/server');


	var initialCompile = true;

	var compiler = webpack(webpackConfig);

	var devServer = new WebpackDevServer(compiler, {
	contentBase : 'http://lvh.me:' + serverConfig.devPort,
	publicPath : webpackConfig.output.publicPath,
	hot : true,
	inline : true,
	historyApiFallback: true,
	quiet : false,
	noInfo : false,
	lazy : false,
	stats : {
	colors : true,
	hash : false,
	version : false,
	chunks : false,
	children: false
	}
	});

	devServer.listen(serverConfig.devPort, 'localhost', function(err) {
	if (err) console.error(err);
	console.log('=> 🔥 Webpack development server is running on port %s', serverConfig.devPort);
	});

	// This part will notify gulp that assets are compiled
	// Gulp will start application Express server then
	// (and it'll pick up assets filenames from json manifest to inject them in html)
	compiler.plugin('done', function() {
	if (initialCompile) {
	initialCompile = false;
	process.stdout.write('Webpack: Done!');
	}
	});