Merge pull request #574 from webpack/develop

bebraw · web-flow · commit b07ed9b74413 · 2017-01-01T16:01:38.000+02:00
Sync develop with master
diff --git a/components/navigation/navigation-style.scss b/components/navigation/navigation-style.scss
@@ -22,6 +22,7 @@
   display: flex;
   font-size: 1.5em;
   position: absolute;
+  top: .64em;
   align-items: center;
   color: getColor(white);
   cursor: pointer;
@@ -34,6 +35,10 @@
   @include break {
     display: none;
   }
+
+  .icon-menu {
+    display: inline-flex;
+  }
 }
 
 .navigation__logo {
diff --git a/components/page/page.jsx b/components/page/page.jsx
@@ -6,9 +6,10 @@ import Sidecar from '../sidecar/sidecar';
 import Contributors from '../contributors/contributors';
 import './page-style';
 import '../sidebar/sidebar-style';
+import { trimEnd } from 'lodash';
 
 export default ({ section, page }) => {
-  let edit = `https://github.com/webpack/webpack.js.org/edit/develop/content/${page.url}.md`;
+  let edit = `https://github.com/webpack/webpack.js.org/edit/develop/content/${trimEnd(page.url, '/')}.md`;
 
   return (
     <Container className="page">
diff --git a/components/sidebar-item/sidebar-item.jsx b/components/sidebar-item/sidebar-item.jsx
@@ -16,6 +16,7 @@ export default class SidebarItem extends React.Component {
     let emptyMod = !anchors.length ? 'sidebar-item--empty' : '';
     let active = `/${currentPage}` === url;
     let openMod = (active || this.state.open) ? 'sidebar-item--open' : '';
+    let anchorUrl = (active) ? '#' : url + '#';
 
     return (
       <div className={ `sidebar-item ${emptyMod} ${openMod}` }>
@@ -25,7 +26,7 @@ export default class SidebarItem extends React.Component {
           {
             anchors.map((anchor, j) => (
               <li className="sidebar-item__anchor" key={ `anchor-${index}-${j}` }>
-                <a href={ '#' + anchor.id }>{ anchor.title}</a>
+                <a href={ anchorUrl + anchor.id }>{ anchor.title}</a>
               </li>
             ))
           }
diff --git a/content/api/cli.md b/content/api/cli.md
@@ -169,18 +169,17 @@ These options makes the build watch for changes in files of the dependency graph
 
 ### Optimize Options
 
-These options allow to manipulate optimisations for a production build using webpack
+These options allow you to manipulate optimisations for a production build using webpack
 
 | Parameter                 | Explanation                                            | Plugin used                          |
 |---------------------------|--------------------------------------------------------|--------------------------------------|
-| --optimize-dedupe         | Optimize duplicate module sources in the bundle        | DedupePlugin                         |
 | --optimize-max-chunks     | Try to keep the chunk count below a limit              | LimitChunkCountPlugin                |
 | --optimize-min-chunk-size | Try to keep the chunk size above a limit               | MinChunkSizePlugin                   |
 | --optimize-minimize       | Minimize javascript and switches loaders to minimizing | UglifyJsPlugin & LoaderOptionsPlugin |
 
 ### Resolve Options
 
-These allow to configure the webpack resolver with aliases and extensions.
+These allow you to configure the webpack resolver with aliases and extensions.
 
 | Parameter              | Explanation                                             | Example                                     |
 |------------------------|---------------------------------------------------------|---------------------------------------------|
diff --git a/content/concepts/entry-points.md b/content/concepts/entry-points.md
@@ -97,4 +97,4 @@ const config = {
 
 - Use `CommonsChunkPlugin` to create bundles of shared application code between each page. Multi-page applications that reuse a lot of code/modules between entry points can greatly benefit from these techniques, as the amount of entry points increase.
 
-T> As a rule of thumb: for one HTML use exactly one entry point.
+T> As a rule of thumb: for each HTML document use exactly one entry point.
diff --git a/content/concepts/hot-module-replacement.md b/content/concepts/hot-module-replacement.md
@@ -4,54 +4,92 @@ sort: 11
 contributors:
 - SpaceK33z
 - sokra
+- GRardB
 ---
 
-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.
+Hot Module Replacement (HMR) exchanges, adds, or removes
+[modules](/concepts/modules/) while an application is running without a
+page reload. This allows you to speed up development time by updating
+individual modules when they are changed without refreshing the page.
 
 ## How Does It Work?
 
 ### From The App View
 
-The app code asks the HMR runtime to check for 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).
+1. The app code asks the HMR runtime to check for updates.
+2. The HMR runtime downloads the updates (asynchronously) and tells the app
+code that an update is available.
+3. The app code then asks the HMR runtime to apply the updates.
+4. The HMR runtime applies the update (synchronously).
+
+You can set up HMR so that this process happens automatically, or you can
+choose to require user interaction for updates to occur.
 
 ### 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:
+In addition to the normal assets, the compiler needs to emit an "update"
+to allow updating from previous version to the new version. The "update"
+consists of two parts:
 
-1. the update manifest (JSON)
-2. one or multiple update chunks (JavaScript)
+1. The update manifest (JSON)
+2. One or more update chunks (JavaScript)
 
-The manifest contains the new compilation hash and a list of all update chunks (2.).
+The manifest contains the new compilation hash and a list of all update chunks.
 
-The update chunks contain code for all updated modules in this chunk (or a flag if a module was removed).
+Each update chunk contains code for all updated modules in the respective chunk
+(or a flag indicating that the module was removed).
 
-The compiler addtionally makes sure that module and chunk ids are consistent between these builds. It uses a "records" json file to store them between builds (or it stores them in memory).
+The compiler makes sure that module IDs and chunk IDs are consistent
+between these builds. It typically stores these IDs in memory (for example, when
+using [webpack-dev-server](/configuration/dev-server/)), but it's also possible to
+store them in a JSON file.
 
 ### From The Module View
 
-HMR is an opt-in feature that affects only modules containing HMR code. You can consider patching styling through style-loader as a good example. To make this work, style-loader implements the HMR interface. Implementing it you describe what should happen when a module is updated. In this case we simply replace the styling with the one received through HMR.
+HMR is an opt-in feature that only affects modules containing HMR code. One example
+would be patching styling through the [style-loder](https://github.com/webpack/style-loader).
+In order for patching to work, style-loader implements the HMR interface; when it
+receives an update through HMR, it replaces the old styles with the new ones.
 
-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 an 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).
+Similarly, when implementing the HMR interface in a module, you can describe what should
+happen when the module is updated. However, 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 that a single handler can handle an 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 additional code is emitted to track module `parents` and `children`.
-
-On the management side the runtime supports two methods: `check` and `apply`.
+For the module system runtime, additional code is emitted to track module `parents` and `children`.
 
-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.
+On the management side, the runtime supports two methods: `check` and `apply`.
 
-For each new chunk request in the ready state the update chunk is also downloaded.
+A `check` makes an HTTP request to the update manifest. If this request fails,
+there is no update available. If it succeeds, 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 are stored in the runtime.
+When all update chunks have been downloaded and are ready to be applied, the runtime
+switches into the `ready` state.
 
-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 marks 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.
+The `apply` method flags all updated modules as invalid. For each invalid module,
+there needs to be an update handler in the module or update handlers in its parent(s).
+Otherwise, the invalid flag bubbles up and marks its parent(s) as invalid too. Each bubble
+continues until the app's entry point or a module with an update handler is reached
+(whichever comes first). 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.
+Afterwards, all invalid modules are disposed (via the dispose handler) and unloaded.
+The current hash is then 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 a 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.
+You can use it in development as a LiveReload replacement.
+[webpack-dev-server](/configuration/dev-server/) supports a
+hot mode in which it tries to update with HMR before trying to reload the whole page. See how
+to implement [HMR with React](/guides/hmr-react) as an 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.
+Some loaders already generate modules that are hot-updateable. For example, the `style-loader`
+can swap out a page's stylesheets. For modules like this, 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.
+webpack's power lies in its customizability, and there are *many* ways of configuring HMR
+depending on the needs of a particular project.
diff --git a/content/concepts/index.md b/content/concepts/index.md
@@ -86,6 +86,8 @@ const config = {
     ]
   }
 };
+
+module.exports = config;
 ```
 
 In the configuration above we have defined a `rules` property for a single module with two required properties: `test`, and `use`. This tells webpack's compiler the following:
diff --git a/content/concepts/plugins.md b/content/concepts/plugins.md
@@ -87,4 +87,4 @@ module.exports = config;
   });
 ```
 
-T> Did you know: The example seen above is extremely similar to the [webpack runtime itself!](https://github.com/webpack/webpack/blob/master/bin/webpack.js#L290-L292) There are lots of great usage examples hiding in the [webpack source code](https://github.com/webpack/webpack) that you can apply to your own configurations and scripts!
+T> Did you know: The example seen above is extremely similar to the [webpack runtime itself!](https://github.com/webpack/webpack/blob/e7087ffeda7fa37dfe2ca70b5593c6e899629a2c/bin/webpack.js#L290-L292) There are lots of great usage examples hiding in the [webpack source code](https://github.com/webpack/webpack) that you can apply to your own configurations and scripts!
diff --git a/content/configuration/index.md b/content/configuration/index.md
@@ -12,7 +12,7 @@ Webpack is fed via a configuration object. It is passed in one of two ways depen
 
 T> New to webpack? Check out our guide to some of webpack's [core concepts](/concepts) to get started!
 
-T> Notice that throughout the configuration we use Node's built-in [path module](https://nodejs.org/api/path.html). This prevents file path issues between operating systems. See [this section](https://nodejs.org/api/path.html#path_windows_vs_posix) for more.
+T> Notice that throughout the configuration we use Node's built-in [path module](https://nodejs.org/api/path.html) and prefix it with the [__dirname](https://nodejs.org/docs/latest/api/globals.html#globals_dirname) global. This prevents file path issues between operating systems and allows relative paths to work as expected. See [this section](https://nodejs.org/api/path.html#path_windows_vs_posix) for more info on POSIX vs. Windows paths.
 
 ## Options
 
diff --git a/content/configuration/output.md b/content/configuration/output.md
@@ -324,9 +324,8 @@ In this case, you need the another property to name your module:
 
 ```javascript
 output: {
-	name: "MyLibrary",
-	libraryTarget: "umd",
-	umdNamedDefine: true
+	library: "MyLibrary",
+	libraryTarget: "umd"
 }
 ```
 
diff --git a/content/configuration/resolve.md b/content/configuration/resolve.md
@@ -142,7 +142,7 @@ which is what enables users to leave off the extension when importing:
 import File from '../path/to/file'
 ```
 
-W> Using this will **override the default array**, meaning that webpack will no longer try to resolve modules using the default extensions. For modules that are imported with their extension, e.g. `import SomeFile from "./somefile.ext"`, to be properly resolved, an empty string must be included in the array.
+W> Using this will **override the default array**, meaning that webpack will no longer try to resolve modules using the default extensions. For modules that are imported with their extension, e.g. `import SomeFile from "./somefile.ext"`, to be properly resolved, a string containing "\*" must be included in the array.
 
 
 ## `resolve.mainFields`
diff --git a/content/configuration/stats.md b/content/configuration/stats.md
@@ -34,7 +34,7 @@ For more granular control, it is possible to specify exactly what information yo
 stats: {
   // Add asset Information
   assets: true,
-  // Sort assets by a filed
+  // Sort assets by a field
   assetsSort: "field",
   // Add information about cached (not built) modules
   cached: true,
diff --git a/content/get-started/index.md b/content/get-started/index.md
@@ -4,6 +4,7 @@ sort: 3
 contributors:
   - bebraw
   - varunjayaraman
+  - cntanglijun
 ---
 
 webpack is a tool to build JavaScript modules in your application. To start using `webpack` from its [cli](/api/cli) or [api](/api/node), follow the [Installation instructions](/get-started/install-webpack).
@@ -16,8 +17,9 @@ Create a demo directory to try out webpack. [Install webpack](/get-started/insta
 ```bash
 mkdir webpack-demo && cd webpack-demo
 npm init -y
-npm install --save-dev webpack
-webpack --help # Shows a list of valid cli commands
+npm install --save-dev webpack@beta
+./node_modules/.bin/webpack --help # Shows a list of valid cli commands
+.\node_modules\.bin\webpack --help # For windows users
 npm install --save lodash
 ```
 
diff --git a/content/get-started/install-webpack.md b/content/get-started/install-webpack.md
@@ -10,10 +10,12 @@ sort: 1
 
 Before getting started, make sure you have a fresh version of [Node.js](https://nodejs.org/en/) installed. The current LTS is an ideal starting point. You may run into a variety of issues with the older versions as they may be missing functionality webpack or related packages might need.
 
+Note that this documentation is for webpack 2, for which there is not yet a stable release.  You can get the most recent beta by installing with the `beta` tag (see below).
+
 ### Global Installation
 
 ``` bash
-npm install webpack -g
+npm install webpack@beta -g
 ```
 
 The `webpack` command is now available globally.
@@ -23,7 +25,7 @@ However, this is not a recommended practice. This locks you down to a specific v
 ### Local Installation
 
 ``` bash
-npm install webpack --save-dev
+npm install webpack@beta --save-dev
 
 npm install webpack@<version> --save-dev
 ```
diff --git a/content/guides/code-splitting.md b/content/guides/code-splitting.md
@@ -14,9 +14,9 @@ There are mainly two kinds of code splitting that can be accomplished with webpa
 
 ### Vendor code splitting
 
-A typical application can depend on many third party libraries for framework/functionality needs. Unlike the application code, code present in these libraries do not change very often. 
+A typical application can depend on many third party libraries for framework/functionality needs. Unlike application code, code present in these libraries does not change very often. 
 
-If we keep code from these libraries onto its own bundle, separate from the application code, we can leverage browser's caching mechanism to cache these files for longer durations on the end user's machine. 
+If we keep code from these libraries in its own bundle, separate from the application code, we can leverage the browser's caching mechanism to cache these files for longer durations on the end user's machine. 
 
 For this to work, the `hash` portion in the vendor filename must remain constant, regardless of application code changes. Learn [how to split vendor/library](/guides/code-splitting-libraries) code using the CommonsChunkPlugin.
 
@@ -31,7 +31,7 @@ Learn [how to split css](/guides/code-splitting-css) using the `ExtractTextWebpa
 
 While resource splitting of the previous kind requires the user to specify the split points upfront in the configuration, one can also create dynamic split points in the application code.
 
-This can be used for more granular chunking of code, for eg. as per our application routes or as per predicted user behaviour. This allows the user to load non-essential assets on demand.
+This can be used for more granular chunking of code, for example, per our application routes or as per predicted user behaviour. This allows the user to load non-essential assets on demand.
 
 ### Code splitting with `require.ensure()`
 
diff --git a/content/guides/dependency-management.md b/content/guides/dependency-management.md
@@ -20,7 +20,7 @@ Example:
 require("./template/" + name + ".ejs");
 ```
 
-Webpack parses the require statement and extracts some information:
+Webpack parses the `require()` call and extracts some information:
 
 ```
 Directory: ./template
@@ -45,8 +45,9 @@ This means dynamic requires are supported but will cause all possible modules to
 
 ## `require.context`
 
-You can create your own context with the require.context function. 
-It allow to pass a directory, regular expression and a flag if subdirectories should be searched too.
+You can create your own context with the `require.context()` function.
+It allows you to pass in a directory to search, a flag indicating whether subdirectories should be searched
+too, and a regular expression to match files against.
 
 Webpack parses for `require.context()` in the code while building.
 
@@ -84,7 +85,7 @@ function importAll (r) {
 }
 importAll(require.context('../components/', true, /\.js$/));
   ```
-  
+
   ```javascript
 var cache = {};
 function importAll (r) {
diff --git a/content/guides/hmr-react.md b/content/guides/hmr-react.md
diff --git a/content/guides/migrating.md b/content/guides/migrating.md
diff --git a/content/guides/production-build.md b/content/guides/production-build.md
diff --git a/content/plugins/loader-options-plugin.md b/content/plugins/loader-options-plugin.md
diff --git a/content/plugins/source-map-dev-tool-plugin.md b/content/plugins/source-map-dev-tool-plugin.md
diff --git a/styles/markdown.scss b/styles/markdown.scss

Original file line number	Diff line number	Diff line change
`@@ -97,4 +97,4 @@ const config = {`
`97`	`97`
`98`	`98`	- Use `CommonsChunkPlugin` to create bundles of shared application code between each page. Multi-page applications that reuse a lot of code/modules between entry points can greatly benefit from these techniques, as the amount of entry points increase.
`99`	`99`
`100`		`-T> As a rule of thumb: for one HTML use exactly one entry point.`
	`100`	`+T> As a rule of thumb: for each HTML document use exactly one entry point.`
Original file line number	Diff line number	Diff line change
`@@ -86,6 +86,8 @@ const config = {`
`86`	`86`	`]`
`87`	`87`	`}`
`88`	`88`	`};`
	`89`	`+`
	`90`	`+module.exports = config;`
`89`	`91`	```
`90`	`92`
`91`	`93`	In the configuration above we have defined a `rules` property for a single module with two required properties: `test`, and `use`. This tells webpack's compiler the following: