diff --git a/content/plugins/dll-plugin.md b/content/plugins/dll-plugin.md new file mode 100644 index 000000000000..04a29096524a --- /dev/null +++ b/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) diff --git a/content/plugins/index.md b/content/plugins/index.md index 081225423049..041b3c1d703c 100644 --- a/content/plugins/index.md +++ b/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|