Merge pull request #584 from simon04/production-build

production-build: enhance documentation

Author: bebraw

content/guides/production-build.md

@@ -4,79 +4,73 @@ sort: 13
 contributors:
   - henriquea
   - rajagopal4890
+  - markerikson
+  - simon04
 ---
 
-Generating production builds with webpack is straight-forward. There are three things to keep in mind:
+This page explains how to generate production builds with webpack.
 
-- Source Maps
-- Node environment
-- Minification
+## The automatic way
 
-## Source Maps
+Running `webpack -p` (or equivalently `webpack --optimize-minimize --define process.env.NODE_ENV="production"`). This performs the following steps:
 
-We encourage you to have Source Maps enabled in production. They are useful for debugging and to run benchmark tests. Webpack can generate inline Source Maps included in the bundles or separated files.
-
-In your configuration, use the `devtools` object to set the Source Map type. We currently support seven types of Source Maps. You can find more information about them in our [configuration](/configuration/devtool) documentation page.
-
-One of the good options to go is using `cheap-module-source-map` which simplifies the Source Maps to a single mapping per line.
-
-## Node environment variable
-
-The second step is to tell webpack to generate a production build by setting the Node.js environment variable to `production`. webpack will not include any extra useful code, warnings and checks used in development.
+- Minification using `UglifyJsPlugin`
+- Runs the `LoaderOptionsPlugin`, see its [documentation](/plugins/loader-options-plugin)
+- Sets the Node environment variable
 
-The `DefinePlugin` creates **compile** time constants. Useful for injecting your Node.js environment as seen below.
+### Minification
 
-?> TODO: Add a link to the `ProvidePlugin` documentation
+webpack comes with `UglifyJsPlugin`, which runs [UglifyJS](http://lisperator.net/uglifyjs/) in order to minimize the output. The plugin supports all of [UglifyJS options](https://github.com/mishoo/UglifyJS2#usage). Specifying `--optimize-minimize` on the command line, the following plugin configuration is added:
 
 ```js
 // webpack.config.js
-
 const webpack = require('webpack');
 
 module.exports = {
   /*...*/
-  plugins: [
-    new webpack.DefinePlugin({
-      'process.env': {
-        'NODE_ENV': JSON.stringify('production')
-      }
+  plugins:[
+    new webpack.optimize.UglifyJsPlugin({
+      sourceMap: options.devtool && (options.devtool.indexOf("sourcemap") >= 0 || options.devtool.indexOf("source-map") >= 0)
     })
   ]
-  /*...*/
 };
 ```
 
-T> Spoiler: Setting the env var only won't make your bundle smaller. This take us to the last step:
+Thus, depending on the [devtool options](/configuration/devtool), Source Maps are generated.
 
-## Minification
+### Source Maps
 
-webpack comes with UglifyJS plugin which minimize the output. You can pass an object containing [UglifyJS options](https://webpack.github.io/docs/list-of-plugins.html#uglifyjsplugin).
+We encourage you to have Source Maps enabled in production. They are useful for debugging and to run benchmark tests. Webpack can generate inline Source Maps included in the bundles or separated files.
+
+In your configuration, use the `devtools` object to set the Source Map type. We currently support seven types of Source Maps. You can find more information about them in our [configuration](/configuration/devtool) documentation page.
+
+One of the good options to go is using `cheap-module-source-map` which simplifies the Source Maps to a single mapping per line.
+
+### Node environment variable
+
+Running `webpack -p` (or `--define process.env.NODE_ENV="production"`) invokes the [`DefinePlugin`](/plugins/define-plugin) in the following way:
 
 ```js
 // webpack.config.js
-
 const webpack = require('webpack');
 
 module.exports = {
   /*...*/
   plugins:[
     new webpack.DefinePlugin({
-      'process.env':{
-        'NODE_ENV': JSON.stringify('production')
-      }
-    }),
-    new webpack.optimize.UglifyJsPlugin({
-      compress:{
-        warnings: true
-      }
+      'process.env.NODE_ENV': JSON.stringify('production')
     })
   ]
-  /*...*/
 };
 ```
-## Configuring webpack for multiple environments
 
-When we do have multiple configurations in mind for different environments, the easiest way is to write seperate js files for 
+The `DefinePlugin` performs search-and-replace operations on the original source code. Any occurrence of `process.env.NODE_ENV` in the imported code is replaced by by `"production"`. Thus, checks like `if (process.env.NODE_ENV !== 'production') console.log('...')` are evaluated to `if (false) console.log('...')` and finally minified away using `UglifyJS`.
+
+T> Technically, `NODE_ENV` is a system environment variable that Node.js exposes into running scripts. It is used by convention to determine development-vs-production behavior, by both server tools, build scripts, and client-side libraries. Contrary to expectations, `process.env.NODE_ENV` is not set to `"production"` __within__ the build script `webpack.config.js`, see [#2537](https://github.com/webpack/webpack/issues/2537). Thus, conditionals like `process.env.NODE_ENV === 'production' ? '[name].[hash].bundle.js' : '[name].bundle.js'` do not work as expected.
+
+## The manual way: Configuring webpack for multiple environments
+
+When we do have multiple configurations in mind for different environments, the easiest way is to write seperate js files for
 each environment. For example:
 
 ** dev.js **

content/plugins/define-plugin.md

@@ -0,0 +1,64 @@
+---
+title: DefinePlugin
+---
+
+``` javascript
+new webpack.DefinePlugin(definitions)
+```
+
+The `DefinePlugin` allows you to create global constants which can be configured at **compile** time. This can be very useful for allowing different behaviour between development builds and release builds. For example, you might use a global constant to determine whether logging takes place; perhaps you perform logging in your development build but not in the release build. That's the sort of scenario the `DefinePlugin` facilitates.
+
+**Example:**
+
+``` javascript
+new webpack.DefinePlugin({
+  PRODUCTION: JSON.stringify(true),
+  VERSION: JSON.stringify("5fa3b9"),
+  BROWSER_SUPPORTS_HTML5: true,
+  TWO: "1+1",
+  "typeof window": JSON.stringify("object")
+})
+```
+
+``` javascript
+console.log("Running App version " + VERSION);
+if(!BROWSER_SUPPORTS_HTML5) require("html5shiv");
+```
+
+T> Note that because the plugin does a direct text replacement, the value given to it must include actual quotes inside of the string itself. Typically, this is done either with alternate quotes, such as `'"production"'`, or by using `JSON.stringify('production')`.
+
+Each key passed into `DefinePlugin` is an identifier or multiple identifiers joined with `.`.
+
+* If the value is a string it will be used as a code fragment.
+* If the value isn't a string, it will be stringified (including functions).
+* If the value is an object all keys are defined the same way.
+* If you prefix `typeof` to the key, it's only defined for typeof calls.
+
+The values will be inlined into the code which allows a minification pass to remove the redundant conditional.
+
+**Example:**
+
+``` javascript
+if (!PRODUCTION) {
+  console.log('Debug info')
+}
+if (PRODUCTION) {
+  console.log('Production log')
+}
+`````
+After passing through webpack with no minification results in:
+
+``` javascript
+if (!true) {
+  console.log('Debug info')
+}
+if (true) {
+  console.log('Production log')
+}
+```
+
+and then after a minification pass results in:
+
+``` javascript
+console.log('Production log')
+```