diff --git a/content/plugins/dll-plugin.md b/content/plugins/dll-plugin.md new file mode 100644 index 000000000000..9fe8cb6ceb5f --- /dev/null +++ b/content/plugins/dll-plugin.md @@ -0,0 +1,159 @@ +--- +title: DllPlugin +contributors: + - aretecode + - sokra + - opiepj + - simon04 +--- + +## 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][src-TemplatedPathPlugin]: `[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). + + +W> Keep the `name` consistent with `output.library`. + +Combine this plugin with `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) +* `content` (optional): the mappings from request to module id (defaults to `manifest.content`) +* `manifest` (object): an object containing `content` and `name` +* `name` (optional): the name where the dll is exposed (defaults to `manifest.name`) (see also `externals`) +* `scope` (optional): prefix which is used for accessing the content of the dll +* `sourceType` (optional): how the dll is exposed ([libraryTarget][docs-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. + + +### Modes + +Can be used in two different modes: + +#### **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][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. + +T> [See an example use of mapped mode][examples-dll-source-type-and-dependencies] + + + +# Usage + +W> `DllReferencePlugin` and `DllPlugin` are used in _separate_ webpack configs. + + +```javascript +// webpack.vendor.config.js +new webpack.DllPlugin({ + context: __dirname, + name: "[name]_[hash]" + path: path.join(__dirname, "manifest.json"), +}) +``` + +```javascript +// webpack.app.config.js +new webpack.DllReferencePlugin({ + context: __dirname, + manifest: require("./manifest.json"), + name: "./my-dll.js", + scope: "xyz", + sourceType: "commonsjs2" +}) +``` + + +## **Examples** + +### [vendor and app][examples-dll-app-and-vendor] + +_A config for vendor, and another config for app (most common use case.) Built scripts are used in example HTML file. Demonstrates library, multiple configs, minimal example._ + +T> Single `DllPlugin` with a single `DllReferencePlugin`. + +### [sourceType and dependencies][examples-dll-source-type-and-dependencies] + +_Uses `libraryTarget` + `sourceType` `"commonjs2"` to create a vendor bundle, and a dependency bundle, on nodejs._ + +T> Single `DllPlugin`, with multiple `DllReferencePlugins`. + +### [vendor][examples-dll-vendor] and [user][examples-dll-user] + +_Two separate example folders. Demonstrates scope, and context._ + +T> Multiple `DllPlugins` and multiple `DllReferencePlugins`. + + +### related +- [code splitting example][examples-explicit-vendor-chunk] + + + +## More + +#### Source +- [DllPlugin source][src-DllPlugin] +- [DllReferencePlugin source][src-DllReferencePlugin] +- [DllModuleFactory source][src-DllModuleFactory] +- [ManifestPlugin source][src-ManifestPlugin] + +#### Tests +- [DllPlugin creation test][tests-DllPlugin-0] +- [DllPlugin without scope test][tests-DllPlugin-2] +- [DllReferencePlugin use Dll test][tests-DllPlugin-1] + + +[examples-examples]: https://github.com/webpack/webpack/tree/master/examples +[examples-dll-vendor]: https://github.com/webpack/webpack/tree/master/examples/dll +[examples-dll-user]: https://github.com/webpack/webpack/tree/master/examples/dll-user +[examples-dll-app-and-vendor]: https://github.com/webpack/webpack/tree/master/examples/dll-app-and-vendor +[examples-dll-source-type-and-dependencies]: https://github.com/webpack/webpack/tree/master/examples/dll-source-type-and-dependencies/README.md +[examples-explicit-vendor-chunk]: https://github.com/webpack/webpack/tree/master/examples/explicit-vendor-chunk/README.md + +[src-DllReferencePlugin]: https://github.com/webpack/tree/master/lib/DllReferencePlugin.js +[src-DllPlugin]: https://github.com/webpack/webpack/tree/master/lib/DllPlugin.js +[src-DllEntryPlugin]: https://github.com/webpack/webpack/blob/master/lib/DllEntryPlugin.js +[src-DllModuleFactory]: https://github.com/webpack/webpack/blob/master/lib/DllModuleFactory.js +[src-ManifestPlugin]: https://github.com/webpack/webpack/blob/master/lib/LibManifestPlugin.js +[src-TemplatedPathPlugin]: https://github.com/webpack/webpack/blob/master/lib/TemplatedPathPlugin.js + +[tests-DllPlugin-0]: https://github.com/webpack/webpack/tree/master/test/configCases/dll-plugin/0-create-dll/webpack.config.js +[tests-DllPlugin-1]: https://github.com/webpack/webpack/tree/master/test/configCases/dll-plugin +[tests-DllPlugin-2]: https://github.com/webpack/webpack/tree/master/test/configCases/dll-plugin/2-use-dll-without-scope/webpack.config.js + +[docs-libraryTarget]: https://webpack.js.org/configuration/output/#output-librarytarget 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|