Add docs for use with webpack-hot-middleware and production setup (#11)

README.md

@@ -1,7 +1,5 @@
 # Webpack Hot Server Middleware [![Build Status](https://travis-ci.org/60frames/webpack-hot-server-middleware.svg?branch=master)](https://travis-ci.org/60frames/webpack-hot-server-middleware) [![npm version](https://badge.fury.io/js/webpack-hot-server-middleware.svg)](https://badge.fury.io/js/webpack-hot-server-middleware) [![Coverage Status](https://coveralls.io/repos/github/60frames/webpack-hot-server-middleware/badge.svg?branch=master)](https://coveralls.io/github/60frames/webpack-hot-server-middleware?branch=master)
 
-## What?
-
 Webpack Hot Server Middleware is designed to be used in conjunction with [`webpack-dev-middleware`](https://github.com/webpack/webpack-dev-middleware/) (and optionally [`webpack-hot-middleware`](https://github.com/glenjamin/webpack-hot-middleware/)) to hot update Webpack bundles on the server.
 
 ## Why?
@@ -58,13 +56,13 @@ app.use(serverRenderer());
 app.listen(6060);
 ```
 
-Given this setup it's fairly easy to hook up hot module reloading for your client bundle using `webpack-dev-server` or `webpack-hot-middleware` however these middlewares don't handle server bundles meaning you need to constantly restart your server whenever a change is made.
+Given this setup it's fairly easy to hook up hot module replacement for your client bundle using `webpack-dev-server` or `webpack-hot-middleware` however these middlewares don't handle server bundles meaning you need to frequently restart your server to see the latest changes.
 
-Webpack Hot Server Middleware will ensure that the server bundle used is always the latest compilation without requiring a restart.
+Webpack Hot Server Middleware solves this problem, ensuring the server bundle used is always the latest compilation without requiring a restart. Additionally it allows your client and server bundle to share the same Webpack cache for faster builds and uses an in-memory bundle on the server to avoid hitting the disk.
 
 ## How?
 
-It turns out hot reloading a Webpack bundle on the server is much easier than on the client as you don't have any state to preserve because middleware is almost always necessarily stateless so the entire bundle can be replaced at the top level whenever a change occurs.
+It turns out hot module replacement is much easier on the server than on the client as you don't have any state to preserve because middleware is almost always necessarily stateless, so the entire bundle can be replaced at the top level whenever a change occurs.
 
 ### Usage
 
@@ -114,6 +112,61 @@ Now whenever Webpack rebuilds, the new bundle will be used both client and *serv
 
 A simple example can be found in the [example](example) directory and a more real world example can be seen in the [60fram.es boilerplate](https://github.com/60frames/react-boilerplate).
 
+### Usage with `webpack-hot-middleware`
+
+`webpack-hot-middleware` needs to be mounted *before* `webpack-hot-server-middleware` to ensure client hot module replacement requests are handled correctly, e.g.
+
+```js
+const express = require('express');
+const webpack = require('webpack');
+const webpackDevMiddleware = require('webpack-dev-middleware');
+const webpackHotMiddleware = require('webpack-hot-middleware');
+const webpackHotServerMiddleware = require('webpack-hot-server-middleware');
+const config = require('./webpack.config.js');
+const app = express();
+
+const compiler = webpack(config);
+
+app.use(webpackDevMiddleware(compiler));
+// NOTE: Only the client bundle needs to be passed to `webpack-hot-middleware`.
+app.use(webpackHotMiddleware(compiler.compilers.find(compiler => compiler.name === 'client')));
+app.use(webpackHotServerMiddleware(compiler));
+
+app.listen(6060);
+```
+
+### Production Setup
+
+A production setup might conditionally use [`express.static`](https://expressjs.com/en/starter/static-files.html) instead of `webpack-dev-server` and a pre-built server bundle instead of `webpack-hot-server-middleware`, e.g.
+
+```js
+const express = require('express');
+const path = require('path');
+const app = express();
+
+if (process.env.NODE_ENV !== 'production') {
+    const webpack = require('webpack');
+    const webpackDevMiddleware = require('webpack-dev-middleware');
+    const webpackHotMiddleware = require('webpack-hot-middleware');
+    const webpackHotServerMiddleware = require('webpack-hot-server-middleware');
+    const config = require('./webpack.config.js');
+    const compiler = webpack(config);
+    app.use(webpackDevMiddleware(compiler));
+    app.use(webpackHotMiddleware(compiler.compilers.find(compiler => compiler.name === 'client')));
+    app.use(webpackHotServerMiddleware(compiler));
+} else {
+    const DIST_DIR = path.join(__dirname, '../dist');
+    const SERVER_RENDERER_PATH = path.join(DIST_DIR, 'server.js');
+    const CLIENT_STATS_PATH = path.join(DIST_DIR, 'stats.json');
+    const serverRenderer = require(SERVER_RENDERER_PATH);
+    const stats = require(CLIENT_STATS_PATH);
+    app.use(express.static(DIST_DIR));
+    app.use(serverRenderer(stats));
+}
+
+app.listen(6060);
+```
+
 ## License
 
 MIT