DllPlugin & DllReferencePlugin docs (without pending examples)

content/plugins/dll-plugin.md

@@ -0,0 +1,125 @@
+---
+title: DllPlugin
+contributors:
+  - aretecode
+  - sokra
+  - opiepj
+  - simon04
+  - skipjack
+---
+
+## Introduction
+
+The `DllPlugin` and `DllReferencePlugin` provide means to split bundles in a way that can drastically improve build time performance.
+
+[DllPlugin](#DllPlugin) is used in a separate webpack config exclusively to create a dll-only-bundle. It creates a `manifest.json` file, which is used by the [DllReferencePlugin](#DllReferencePlugin) to map dependencies.
+
+[DllReferencePlugin](#DllReferencePlugin) is used in the primary webpack config, it references the dll-only-bundle(s) to require pre-built dependencies.
+
+
+## `DllPlugin`
+
+* `context` (optional): context of requests in the manifest file (defaults to the webpack context.)
+* `name`: name of the exposed dll function ([TemplatePaths](https://github.com/webpack/webpack/blob/master/lib/TemplatedPathPlugin.js): `[hash]` & `[name]` )
+* `path`: **absolute path** to the manifest json file (output)
+
+```javascript
+new webpack.DllPlugin(options)
+```
+
+Creates a `manifest.json` which is written to the given `path`. It contains mappings from require and import requests, to module ids. It is used by the [DllReferencePlugin](#DllReferencePlugin).
+
+Combine this plugin with [`output.library`](/configuration/output/#output-library) option to expose (aka, put into the global scope) the dll function.
+
+
+### `DllReferencePlugin`
+
+* `context`: (**absolute path**) context of requests in the manifest (or content property)
+* `manifest` (object): an object containing `content` and `name`
+* `content` (optional): the mappings from request to module id (defaults to `manifest.content`)
+* `name` (optional): the name where the dll is exposed (defaults to `manifest.name`) (see also [`externals`](/configuration/externals/))
+* `scope` (optional): prefix which is used for accessing the content of the dll
+* `sourceType` (optional): how the dll is exposed ([libraryTarget](/configuration/output/#output-librarytarget))
+
+```javascript
+new webpack.DllReferencePlugin(options)
+```
+
+References a dll manifest file to map dependency names to module ids, then requires them as needed using the internal `__webpack_require__` function.
+
+W> Keep the `name` consistent with [`output.library`](/configuration/output/#output-library).
+
+
+### Modes
+
+This plugin can be used in two different modes, _scoped_ and _mapped_.
+
+#### Scoped Mode
+
+The content of the dll is accessible under a module prefix. i.e. with `scope = "xyz"` a file `abc` in the dll can be access via `require("xyz/abc")`.
+
+T> [See an example use of scope](https://github.com/webpack/webpack/tree/master/examples/dll-user)
+
+#### Mapped Mode
+
+The content of the dll is mapped to the current directory. If a required file matches a file in the dll (after resolving), then the file from the dll is used instead.
+
+Because this happens after resolving every file in the dll bundle, the same paths must be available for the consumer of the dll bundle. i.e. if the dll contains `lodash` and the file `abc`, `require("lodash")` and `require("./abc")` will be used from the dll, rather than building them into the main bundle.
+
+
+## Usage
+
+W> `DllReferencePlugin` and `DllPlugin` are used in _separate_ webpack configs.
+
+**webpack.vendor.config.js**
+
+```javascript
+new webpack.DllPlugin({
+  context: __dirname,
+  name: "[name]_[hash]"
+  path: path.join(__dirname, "manifest.json"),
+})
+```
+
+**webpack.app.config.js**
+
+```javascript
+new webpack.DllReferencePlugin({
+  context: __dirname,
+  manifest: require("./manifest.json"),
+  name: "./my-dll.js",
+  scope: "xyz",
+  sourceType: "commonsjs2"
+})
+```
+
+
+## Examples
+
+### [vendor](https://github.com/webpack/webpack/tree/master/examples/dll) and [user](https://github.com/webpack/webpack/tree/master/examples/dll-user)
+
+_Two separate example folders. Demonstrates scope and context._
+
+T> Multiple `DllPlugins` and multiple `DllReferencePlugins`.
+
+
+### Related
+
+* [code splitting example](https://github.com/webpack/webpack/tree/master/examples/explicit-vendor-chunk/README.md)
+
+
+## References
+
+### Source
+
+* [DllPlugin source](https://github.com/webpack/webpack/tree/master/lib/DllPlugin.js)
+* [DllReferencePlugin source](https://github.com/webpack/tree/master/lib/DllReferencePlugin.js)
+* [DllEntryPlugin source](https://github.com/webpack/webpack/blob/master/lib/DllEntryPlugin.js)
+* [DllModuleFactory source](https://github.com/webpack/webpack/blob/master/lib/DllModuleFactory.js)
+* [ManifestPlugin source](https://github.com/webpack/webpack/blob/master/lib/LibManifestPlugin.js)
+
+### Tests
+
+* [DllPlugin creation test](https://github.com/webpack/webpack/tree/master/test/configCases/dll-plugin/0-create-dll/webpack.config.js)
+* [DllPlugin without scope test](https://github.com/webpack/webpack/tree/master/test/configCases/dll-plugin/2-use-dll-without-scope/webpack.config.js)
+* [DllReferencePlugin use Dll test](https://github.com/webpack/webpack/tree/master/test/configCases/dll-plugin)

content/plugins/index.md

@@ -4,6 +4,7 @@ contributors:
   - simon04
   - gonzoyumo
   - rouzbeh84
+  - aretecode
 ---
 
 webpack has a rich plugin interface. Most of the features within webpack itself use this plugin interface. This makes webpack **flexible**.
@@ -15,6 +16,7 @@ webpack has a rich plugin interface. Most of the features within webpack itself
 |[`CompressionWebpackPlugin`](/plugins/compression-webpack-plugin)|Prepare compressed versions of assets to serve them with Content-Encoding|
 |[`DefinePlugin`](/plugins/define-plugin)|Allows global constants configured at compile time, useful for allowing different behavior between dev/release builds|
 |[`EnvironmentPlugin`](/plugins/environment-plugin)|Shorthand for using the [`DefinePlugin`](./define-plugin) on `process.env` keys.|
+|[`DllPlugin`](/plugins/dll-plugin)|Provide means to split bundles in a way that can drastically improve build time performance.|
 |[`ExtractTextWebpackPlugin`](/plugins/extract-text-webpack-plugin)|Extracts Text (CSS) from your bundles into a separate file (app.bundle.css)|
 |[`HtmlWebpackPlugin`](/plugins/html-webpack-plugin)| Simplifies creation of HTML files (`index.html`) to serve your bundles|
 |[`I18nWebpackPlugin`](/plugins/i18n-webpack-plugin)|Adds i18n support to your bundles|