Improve HMR docs (#389)

SpaceK33z · TheLarkInn · commit e904b07e6973 · 2016-11-22T12:30:41.000-06:00
* Improve HMR docs

* Fix link

* Add concept page for HMR

* Small improvements

Really I just want to trigger a rebuild because the clabot is not working.
diff --git a/content/concepts/hot-module-replacement.md b/content/concepts/hot-module-replacement.md
@@ -0,0 +1,57 @@
+---
+title: Hot Module Replacement
+sort: 11
+contributors:
+- SpaceK33z
+- sokra
+---
+
+Hot Module Replacement (HMR) exchanges, adds, or removes modules while an
+application is running without a page reload. You basically can update changed modules without a full page reload.
+
+## How Does It Work?
+
+### From The App View
+
+The app code asks the HMR runtime to check of updates. The HMR runtime downloads the updates (async) and tell the app code that an update is available. The app code asks the HMR runtime to apply updates. The HMR runtime applies the update (sync). The app code may or may not require user interaction in this process (you decide).
+
+### From The Compiler (webpack) View
+
+In addition to the normal assets the compiler need to emit the "Update" to allow updating from previous version to this version. The "Update" contains two parts:
+
+1. the update manifest (JSON)
+2. one or multiple update chunks (JavaScript)
+
+The manifest contains the new compilation hash and a list of all update chunks (2.).
+
+The update chunks contains code for all updated modules in this chunk (or a flag if a module was removed).
+
+The compiler addtionally makes sure that module and chunk ids as consistent between these builds. It uses a "records" json file to store them between builds (on it store them in memory).
+
+### From The Module View
+
+HMR is an opt-in feature, so it only affects modules that contains HMR code. The documentation describes the API that is available in modules. In general the module developer writes handlers that are called when a dependency of this module is updated. The developer can also write a handler that is called when this module is updated.
+
+In most cases it's not mandatory to write HMR code in every module. If a module has no HMR handlers the update bubbles up. This means a single handler can handle a update to a complete module tree. If a single module in this tree is updated, the complete module tree is reloaded (only reloaded not transferred).
+
+### From The HMR Runtime View (Technical)
+
+For the module system runtime is additional code emitted to track module `parents` and `children`.
+
+On the management side the runtime supports two methods: `check` and `apply`.
+
+A `check` does a HTTP request to the update manifest. When this request fails, there is no update available. Elsewise the list of updated chunks is compared to the list of currently loaded chunks. For each loaded chunk the corresponding update chunk is downloaded. All module updates as stored in the runtime as update. The runtime switches into the `ready` state, meaning an update has been downloaded and is ready to be applied.
+
+For each new chunk request in the ready state the update chunk is also downloaded.
+
+The `apply` method flags all updated modules as invalid. For each invalid module there need to be a update handler in the module or update handlers in every parent. Else the invalid buddles up and mark all parents as invalid too. This process continues until no more "bubble up" occurs. If it bubbles up from an entry point the process fails.
+
+Now all invalid modules are disposed (dispose handler) and unloaded. Then the current hash is updated and all "accept" handlers are called. The runtime switches back to the `idle` state and everything continues as normal.
+
+## What can I do with it?
+
+You can use it in development as LiveReload replacement. webpack-dev-server supports a hot mode which tries to update with HMR before trying to reload the whole page. See how to implement [HMR with React](/guides/hmr-react) for example.
+
+Some loaders already generate modules that are hot-updateable. i.e. the `style-loader` can exchange the stylesheet. You don't need to do anything special.
+
+webpack's power lies in its customizability, and there are *many* ways of configuring HMR given the needs of a particular project.
diff --git a/content/guides/development.md b/content/guides/development.md
@@ -86,7 +86,7 @@ The command above should automatically open your browser on `http://localhost:80
 
 Make a change in one of your files and hit save. You should see that the console is recompiling. After that's done, the page should be refreshed. If nothing happens in the console, you may need to fiddle with [`watchOptions`](/configuration/dev-server#devserver-watchoptions-).
 
-Now you have live reloading working, you can take it even a step further: Hot Module Replacement. This is an interface that makes it possible to swap modules **without a page refresh**. Find out how to [configure HMR](/guides/hmr).
+Now you have live reloading working, you can take it even a step further: Hot Module Replacement. This is an interface that makes it possible to swap modules **without a page refresh**. Find out how to [configure HMR](/guides/hmr-react).
 
 By default **inline mode** is used. This mode injects the client - needed for live reloading and showing build errors - in your bundle. With inline mode you will get build errors and warnings in your DevTools console.
 
diff --git a/content/guides/hmr-react.md b/content/guides/hmr-react.md
@@ -6,12 +6,16 @@ contributors:
   - jhnns
 ---
 
-Hot Module Replacement (HMR) exchanges, adds, or removes modules while an
-application is running without a page reload.
+As explained in detail on the [concept page](/concepts/hot-module-replacement), Hot Module Replacement (HMR)exchanges, adds, or removes modules while an application is running without a page reload.
 HMR is particularly useful in applications using a single state tree,
 since components are "dumb" and will reflect the latest application state, even
 after their source is changed and they are replaced.
 
+The approach described below uses Babel and
+React, but these tools are not necessary for HMR to work.
+
+T> If you'd like to see examples of other approaches, please request them or better yet, [open up a PR with an addition](https://github.com/webpack/webpack.js.org).
+
 ## Project Config
 
 This guide will be demonstrating the use of HMR with Babel,
@@ -39,113 +43,109 @@ Your `.babelrc` file should look like the following:
 {
   "presets": [
     ["es2015", {"modules": false}],
-    //Webpack understands the native import syntax, and uses it for tree shaking
+    // webpack understands the native import syntax, and uses it for tree shaking
 
     "stage-2",
-    //Specifies what level of language features to activate.
-    //Stage 2 is "draft", 4 is finished, 0 is strawman.
-    //See https://tc39.github.io/process-document/
+    // Specifies what level of language features to activate.
+    // Stage 2 is "draft", 4 is finished, 0 is strawman.
+    // See https://tc39.github.io/process-document/
 
     "react"
-    //Transpile React components to JavaScript
+    // Transpile React components to JavaScript
   ],
   "plugins": [
     "react-hot-loader/babel"
-    //Enables React code to work with HMR.
+    // Enables React code to work with HMR.
   ]
 }
 ```
 
-### Webpack config
+### webpack Config
 
-While there's many ways of setting up your Webpack config - via API,
+While there's many ways of setting up your webpack config - via API,
 via multiple or single config files, etc - here is the basic information
 you should have available.
 
 ```js
 const { resolve } = require('path');
 const webpack = require('webpack');
 
-module.exports = env => {
-  return {
-    entry: [
-      'react-hot-loader/patch',
-      //activate HMR for React
+module.exports = {
+  entry: [
+    'react-hot-loader/patch',
+    // activate HMR for React
 
-      'webpack-dev-server/client?http://localhost:8080',
-      //bundle the client for webpack dev server
-      //and connect to the provided endpoint
+    'webpack-dev-server/client?http://localhost:8080',
+    // bundle the client for webpack-dev-server
+    // and connect to the provided endpoint
 
-      'webpack/hot/only-dev-server',
-      //bundle the client for hot reloading
-      //only- means to only hot reload for successful updates
+    'webpack/hot/only-dev-server',
+    // bundle the client for hot reloading
+    // only- means to only hot reload for successful updates
 
 
-      './index.js'
-      //the entry point of our app
-    ],
-    output: {
-      filename: 'bundle.js',
-      //the output bundle
-
-      path: resolve(__dirname, 'dist'),
-
-      publicPath: '/'
-      //necessary for HMR to know where to load the hot update chunks
-    },
-
-    context: resolve(__dirname, 'src'),
-
-    devtool: 'inline-source-map',
-
-    devServer: {
-      hot: true,
-      //activate hot reloading
-
-      contentBase: resolve(__dirname, 'dist'),
-      //match the output path
-
-      publicPath: '/'
-      //match the output publicPath
-    },
-
-    module: {
-      loaders: [
-        { test: /\.js$/,
-          loaders: [
-            'babel-loader',
-          ],
-          exclude: /node_modules/
-        },
-        {
-          test: /\.css$/,
-          loaders: [
-            'style-loader',
-            'css-loader?modules',
-            'postcss-loader',
-          ],
-        },
-      ],
-    },
-
-    plugins: [
-      new webpack.HotModuleReplacementPlugin(),
-      //activates HMR
-
-      new webpack.NamedModulesPlugin(),
-      //prints more readable module names in the browser console on HMR updates
+    './index.js'
+    // the entry point of our app
+  ],
+  output: {
+    filename: 'bundle.js',
+    // the output bundle
+
+    path: resolve(__dirname, 'dist'),
+
+    publicPath: '/'
+    // necessary for HMR to know where to load the hot update chunks
+  },
+
+  context: resolve(__dirname, 'src'),
+
+  devtool: 'inline-source-map',
+
+  devServer: {
+    hot: true,
+    // activate hot reloading
+
+    contentBase: resolve(__dirname, 'dist'),
+    // match the output path
+
+    publicPath: '/'
+    // match the output `publicPath`
+  },
+
+  module: {
+    loaders: [
+      { test: /\.js$/,
+        loaders: [
+          'babel-loader',
+        ],
+        exclude: /node_modules/
+      },
+      {
+        test: /\.css$/,
+        loaders: [
+          'style-loader',
+          'css-loader?modules',
+          'postcss-loader',
+        ],
+      },
     ],
-  };
+  },
+
+  plugins: [
+    new webpack.HotModuleReplacementPlugin(),
+    // activates HMR
+
+    new webpack.NamedModulesPlugin(),
+    // prints more readable module names in the browser console on HMR updates
+  ],
 };
 ```
 
 There's a lot going on above, and not all of it is related to HMR.
 You may benefit from reading the
-[full documentation](https://webpack.github.io/docs/webpack-dev-server.html)
-on webpack dev server, and the [other articles](https://webpack.js.org/concepts/)
-here on webpack.js.org.
+[webpack-dev-server options](/configuration/dev-server) and the [concept pages](/concepts).
 
-The basic assumption here is that your JavaScript entry is located at `./src/index.js`,
+The basic assumption here is that your JavaScript entry is located at `./src/index.js`
 and that you're using CSS Modules for your styling.
 
 Please see the comments inline that explain each portion of the config. The main
@@ -154,7 +154,7 @@ also necessary to include in the `plugins` array.
 
 There are two modules included here for the purposes of this guide.
 The react-hot-loader addition to the entry, as noted above, is necessary to enable
-HMR with React components. The NamedModulesPlugin is a useful addition
+HMR with React components. The `NamedModulesPlugin` is a useful addition
 to better understand what modules are being updated when using HMR.
 
 ### Code
@@ -229,18 +229,18 @@ is included in `App.js`.
 
 ### Package.json
 
-Finally, we need to start up webpack dev server to bundle our code and see HMR in action.
+Finally, we need to start up webpack-dev-server to bundle our code and see HMR in action.
 We can use the following package.json entry:
 
 ```json
 {
   "scripts" : {
-    "start" : "webpack-dev-server --env.dev"
+    "start" : "webpack-dev-server"
   }
 }
 ```
 
-Run `npm start`, open up your browser to `localhost:8080`,
+Run `npm start`, open up your browser to `http://localhost:8080`,
 and you should see the following entries printed in your console.log:
 
 ```bash
@@ -249,7 +249,7 @@ only-dev-server.js:74[HMR] Waiting for update signal from WDS…
 client?c7c8:24 [WDS] Hot Module Replacement enabled.
 ```
 
-Go ahead and edit and save your App.js file.
+Go ahead and edit and save your `App.js` file.
 You should see something like the following in your console.log:
 
 ```bash
@@ -262,4 +262,4 @@ dev-server.js:27 [HMR] App is up to date.
 ```
 
 Note that HMR specifies the paths of the updated modules.
-That's because we're using the NamedModules plugin.
+That's because we're using `NamedModulesPlugin`.
diff --git a/content/guides/hmr.md b/content/guides/hmr.md
