{String\|RegExp\|Array<String\|RegExp>}
The AutomaticPrefetchPlugin
discovers all modules from the previous compilation upfront while watching for changes, trying to improve the incremental build times. Compared to PrefetchPlugin
which discovers a single module upfront.
May or may not have a performance benefit since the incremental build times are pretty fast.
webpack.config.js
module.exports = {
// ...
plugins: [
new webpack.AutomaticPrefetchPlugin()
]
};
A Webpack Plugin for babel-minify - A babel based minifier
npm install babel-minify-webpack-plugin --save-dev
// webpack.config.js
const MinifyPlugin = require("babel-minify-webpack-plugin");
module.exports = {
entry: //...,
output: //...,
plugins: [
new MinifyPlugin(minifyOpts, pluginOpts)
]
}
minifyOpts
are passed on to babel-preset-minify. You can find a list of all available options in the package directory.
Default: {}
test
: Test to match files against. Default: /\.js($|\?)/i
include
: Files to include
. Default: undefined
exclude
: Files to exclude
. Default: undefined
comments
: Preserve Comments. Default: /^\**!|@preserve|@license|@cc_on/
, falsy value to remove all comments. Accepts function, object with property test (regex), and values.sourceMap
: Configure a sourcemap style. Default: webpackConfig.devtoolparserOpts
: Configure babel with special parser options.babel
: Pass in a custom babel-core
instead. Default: require("babel-core")
minifyPreset
: Pass in a custom babel-minify
preset instead. Default: require("babel-preset-minify")
You can also use babel-loader for webpack and include minify
as a preset and should be much faster than using this - as babel-minify will operate on smaller file sizes. But then, why does this plugin exist at all? -
mangle: { topLevel: true }
in minifyOptions.node_modules
from being run through the babel-loader, babel-minify optimizations are not applied to the excluded files as it doesn't pass through the minifier.Boopathi Rajaa | Juho Vepsäläinen | Joshua Wiens | Kees Kluskens | Sean Larkin |
Adds a banner to the top of each generated chunk.
const webpack = require('webpack');
new webpack.BannerPlugin(banner);
// or
new webpack.BannerPlugin(options);
{
banner: string | function, // the banner as string or function, it will be wrapped in a comment
raw: boolean, // if true, banner will not be wrapped in a comment
entryOnly: boolean, // if true, the banner will only be added to the entry chunks
test: string | RegExp | Array,
include: string | RegExp | Array,
exclude: string | RegExp | Array,
}
import webpack from 'webpack';
// string
new webpack.BannerPlugin({
banner: 'hello world'
});
// function
new webpack.BannerPlugin({
banner: (yourVariable) => { return `yourVariable: ${yourVariable}`; }
});
Since webpack 2.5.0, placeholders are evaluated in the banner
string:
import webpack from 'webpack';
new webpack.BannerPlugin({
banner: 'hash:[hash], chunkhash:[chunkhash], name:[name], filebase:[filebase], query:[query], file:[file]'
});
This plugin supports the use of Google's Closure Tools with webpack.
Note: This is the webpack 4 branch.
Closure-Compiler is a full optimizing compiler and transpiler. It offers unmatched optimizations, provides type checking and can easily target transpilation to different versions of ECMASCRIPT.
Closure-Library is a utility library designed for full compatibility with Closure-Compiler.
For webpack 3 support, see https://github.com/webpack-contrib/closure-webpack-plugin/tree/webpack-3
You must install both the google-closure-compiler package as well as the closure-webpack-plugin.
npm install --save-dev closure-webpack-plugin google-closure-compiler
const ClosurePlugin = require('closure-webpack-plugin');
module.exports = {
optimization: {
minimizer: [
new ClosurePlugin({mode: 'STANDARD'}, {
// compiler flags here
//
// for debugging help, try these:
//
// formatting: 'PRETTY_PRINT'
// debug: true,
// renaming: false
})
]
}
};
platform - native
, java
or javascript
. Controls which version to use of closure-compiler.
By default the plugin will attempt to automatically choose the fastest option available.
JAVASCRIPT
does not require the JVM to be installed. Not all flags are supported. JAVA
utilizes the jvm. Utilizes multiple threads for parsing and results in faster compilation for large builds.NATIVE
only available on linux or MacOS. Faster compilation times without requiring a JVM.mode - STANDARD
(default) or AGGRESSIVE_BUNDLE
. Controls how the plugin utilizes the compiler.
STANDARD
mode, closure-compiler is used as a direct replacement for other minifiers as well as most Babel transformations. AGGRESSIVE_BUNDLE
mode, the compiler performs additional optimizations of modules to produce a much smaller filechildCompilations - boolean or function. Defaults to false
.
In order to decrease build times, this plugin by default only operates on the main compilation.
Plugins such as extract-text-plugin and html-webpack-plugin run as child compilations and
usually do not need transpilation or minification. You can enable this for all child compilations
by setting this option to true
. For specific control, the option can be set to a function which
will be passed a compilation object.
Example: function(compilation) { return /html-webpack/.test(compilation.name); }
.
output - An object with either filename
or chunkfilename
properties. Used to override the
output file naming for a particular compilation. See https://webpack.js.org/configuration/output/
for details.
test - An optional string or regular expression to determine whether a chunk is included in the compilation
extraCommandArgs - Optional string or Array of strings to pass to the google-closure-compiler plugin. Can be used to pass flags to the java process.
The plugin controls several compiler flags. The following flags should not be used in any mode:
In this mode, the compiler rewrites CommonJS modules and hoists require calls. Some modules are not compatible with this type of rewriting. In particular, hoisting will cause the following code to execute out of order:
const foo = require('foo');
addPolyfillToFoo(foo);
const bar = require('bar');
Aggressive Bundle Mode utilizes a custom runtime in which modules within a chunk file are all included in the same scope. This avoids the cost of small modules.
In Aggressive Bundle Mode, a file can only appear in a single output chunk. Use the Split Chunks Plugin to split duplicated files into a single output chunk. If a module is utilized by more than one chunk, the plugin will move it up to the first common parent to prevent code duplication.
The concatenatedModules optimization is not compatible with this mode since Closure-Compiler performs an equivalent optimization). The plugin will emit a warning if this optimization is not disabled.
You can add the plugin multiple times. This easily allows you to target multiple output languages.
Use ECMASCRIPT_2015
for modern browsers and ECMASCRIPT5
for older browsers.
Use the output
option to change the filenames of specific plugin instances.
Use <script type="module" src="es6_out_path.js">
to target modern browsers and
<script nomodule src="es5_out_path.js">
for older browsers.
See the es5 and es6 output demo for an example.
In order for webpack to recognize goog.require
, goog.provide
, goog.module
and related primitives,
a separate plugin is shipped.
const ClosurePlugin = require('closure-webpack-plugin');
module.exports = {
plugins: [
new ClosurePlugin.LibraryPlugin({
closureLibraryBase: require.resolve(
'google-closure-library/closure/goog/base'
),
deps: [
require.resolve('google-closure-library/closure/goog/deps'),
'./public/deps.js',
],
})
]
};
The plugin adds extra functionality to support using Closure Library without Closure Compiler.
This is typically used during development mode. When the webpack mode is production
,
only dependency information is provided to webpack as Closure Compiler will natively recognize
the Closure Library primitives.
The Closure Library Plugin is only compatible with the AGGRESSIVE_BUNDLE
mode of the Closure-Compiler
webpack plugin.
closureLibraryBase - (optional) string. Path to the base.js file in Closure-Library.
deps - (optional) string or Array. Closures style dependency mappings. Typically generated by the depswriter.py script included with Closure-Library.
extraDeps - (optional) Object. Mapping of namespace to file path for closure-library provided namespaces.
Chad Killingsworth | Joshua Wiens |
The CommonsChunkPlugin
is an opt-in feature that creates a separate file (known as a chunk), consisting of common modules shared between multiple entry points.
The CommonsChunkPlugin has been removed in webpack v4 legato. To learn how chunks are treated in the latest version, check out the SplitChunksPlugin.
By separating common modules from bundles, the resulting chunked file can be loaded once initially, and stored in cache for later use. This results in page speed optimizations as the browser can quickly serve the shared code from cache, rather than being forced to load a larger bundle whenever a new page is visited.
new webpack.optimize.CommonsChunkPlugin(options);
{
name: string, // or
names: string[],
// The chunk name of the commons chunk. An existing chunk can be selected by passing a name of an existing chunk.
// If an array of strings is passed this is equal to invoking the plugin multiple times for each chunk name.
// If omitted and `options.async` or `options.children` is set all chunks are used, otherwise `options.filename`
// is used as chunk name.
// When using `options.async` to create common chunks from other async chunks you must specify an entry-point
// chunk name here instead of omitting the `option.name`.
filename: string,
// The filename template for the commons chunk. Can contain the same placeholders as `output.filename`.
// If omitted the original filename is not modified (usually `output.filename` or `output.chunkFilename`).
// This option is not permitted if you're using `options.async` as well, see below for more details.
minChunks: number|Infinity|function(module, count) => boolean,
// The minimum number of chunks which need to contain a module before it's moved into the commons chunk.
// The number must be greater than or equal 2 and lower than or equal to the number of chunks.
// Passing `Infinity` just creates the commons chunk, but moves no modules into it.
// By providing a `function` you can add custom logic. (Defaults to the number of chunks)
chunks: string[],
// Select the source chunks by chunk names. The chunk must be a child of the commons chunk.
// If omitted all entry chunks are selected.
children: boolean,
// If `true` all children of the commons chunk are selected
deepChildren: boolean,
// If `true` all descendants of the commons chunk are selected
async: boolean|string,
// If `true` a new async commons chunk is created as child of `options.name` and sibling of `options.chunks`.
// It is loaded in parallel with `options.chunks`.
// Instead of using `option.filename`, it is possible to change the name of the output file by providing
// the desired string here instead of `true`.
minSize: number,
// Minimum size of all common module before a commons chunk is created.
}
The deprecated webpack 1 constructor
new webpack.optimize.CommonsChunkPlugin(options, filenameTemplate, selectedChunks, minChunks)
is no longer supported. Use a corresponding options object instead.
Generate an extra chunk, which contains common modules shared between entry points.
new webpack.optimize.CommonsChunkPlugin({
name: 'commons',
// (the commons chunk name)
filename: 'commons.js',
// (the filename of the commons chunk)
// minChunks: 3,
// (Modules must be shared between 3 entries)
// chunks: ["pageA", "pageB"],
// (Only use these entries)
});
You must load the generated chunk before the entry point:
<script src="commons.js" charset="utf-8"></script>
<script src="entry.bundle.js" charset="utf-8"></script>
Split your code into vendor and application.
module.exports = {
//...
entry: {
vendor: ['jquery', 'other-lib'],
app: './entry'
},
plugins: [
new webpack.optimize.CommonsChunkPlugin({
name: 'vendor',
// filename: "vendor.js"
// (Give the chunk a different name)
minChunks: Infinity,
// (with more entries, this ensures that no other module
// goes into the vendor chunk)
})
]
};
<script src="vendor.js" charset="utf-8"></script>
<script src="app.js" charset="utf-8"></script>
In combination with long term caching you may need to use the
ChunkManifestWebpackPlugin
to avoid the vendor chunk changes. You should also use records to ensure stable module ids, e.g. usingNamedModulesPlugin
orHashedModuleIdsPlugin
.
With Code Splitting, multiple child chunks of an entry chunk can have common dependencies. To prevent duplication these can be moved into the parent. This reduces overall size, but does have a negative effect on the initial load time. If it is expected that users will need to download many sibling chunks, i.e. children of the entry chunk, then this should improve load time overall.
new webpack.optimize.CommonsChunkPlugin({
// names: ["app", "subPageA"]
// (choose the chunks, or omit for all chunks)
children: true,
// (select all children of chosen chunks)
// minChunks: 3,
// (3 children must share the module before it's moved)
});
Similar to the above one, but instead of moving common modules into the parent (which increases initial load time) a new async-loaded additional commons chunk is used. This is automatically downloaded in parallel when the additional chunk is downloaded.
new webpack.optimize.CommonsChunkPlugin({
name: 'app',
// or
names: ['app', 'subPageA'],
// the name or list of names must match the name or names
// of the entry points that create the async chunks
children: true,
// (use all children of the chunk)
async: true,
// (create an async commons chunk)
minChunks: 3,
// (3 children must share the module before it's separated)
});
minChunks
property a functionYou also have the ability to pass the minChunks
property a function. This function is called by the CommonsChunkPlugin
and calls the function with module
and count
arguments.
The module
argument represents each module in the chunks you have provided via the name
/names
property.
module
has the shape of a NormalModule, which has two particularly useful properties for this use case:
module.context
: The directory that stores the file. For example: '/my_project/node_modules/example-dependency'
module.resource
: The name of the file being processed. For example: '/my_project/node_modules/example-dependency/index.js'
The count
argument represents how many chunks the module
is used in.
This option is useful when you want to have fine-grained control over how the CommonsChunk algorithm determines where modules should be moved to.
new webpack.optimize.CommonsChunkPlugin({
name: 'my-single-lib-chunk',
filename: 'my-single-lib-chunk.js',
minChunks: function(module, count) {
// If module has a path, and inside of the path exists the name "somelib",
// and it is used in 3 separate chunks/entries, then break it out into
// a separate chunk with chunk keyname "my-single-lib-chunk", and filename "my-single-lib-chunk.js"
return module.resource && (/somelib/).test(module.resource) && count === 3;
}
});
As seen above, this example allows you to move only one lib to a separate file if and only if all conditions are met inside the function.
This concept may be used to obtain implicit common vendor chunks:
new webpack.optimize.CommonsChunkPlugin({
name: 'vendor',
minChunks: function (module) {
// this assumes your vendor imports exist in the node_modules directory
return module.context && module.context.includes('node_modules');
}
});
In order to obtain a single CSS file containing your application and vendor CSS, use the following minChunks
function together with ExtractTextPlugin
:
new webpack.optimize.CommonsChunkPlugin({
name: 'vendor',
minChunks: function (module) {
// This prevents stylesheet resources with the .css or .scss extension
// from being moved from their original chunk to the vendor chunk
if(module.resource && (/^.*\.(css|scss)$/).test(module.resource)) {
return false;
}
return module.context && module.context.includes('node_modules');
}
});
To extract the webpack bootstrap logic into a separate file, use the CommonsChunkPlugin
on a name
which is not defined as entry
. Commonly the name manifest
is used. See the caching guide for details.
new webpack.optimize.CommonsChunkPlugin({
name: 'manifest',
minChunks: Infinity
});
Since the vendor
and manifest
chunk use a different definition for minChunks
, you need to invoke the plugin twice:
[
new webpack.optimize.CommonsChunkPlugin({
name: 'vendor',
minChunks: function(module){
return module.context && module.context.includes('node_modules');
}
}),
new webpack.optimize.CommonsChunkPlugin({
name: 'manifest',
minChunks: Infinity
}),
];
Prepare compressed versions of assets to serve them with Content-Encoding.
To begin, you'll need to install compression-webpack-plugin
:
$ npm install compression-webpack-plugin --save-dev
Then add the plugin to your webpack
config. For example:
webpack.config.js
const CompressionPlugin = require("compression-webpack-plugin");
module.exports = {
plugins: [new CompressionPlugin()],
};
And run webpack
via your preferred method.
Name | Type | Default | Description |
---|---|---|---|
Name Type Default Description
|
{String\|RegExp\|Array<String\|RegExp>} |
undefined |
Include all assets that pass test assertion |
Name Type Default Description
|
{String\|RegExp\|Array<String\|RegExp>} |
undefined |
Include all assets matching any of these conditions |
Name Type Default Description
|
{String\|RegExp\|Array<String\|RegExp>} |
undefined |
Exclude all assets matching any of these conditions |
Name Type Default Description
|
{String\|Function} |
gzip |
The compression algorithm/function |
Name Type Default Description
|
{Object} |
maximum available compression level, for gzip:
{ level: 9 } |
Compression options for
algorithm |
Name Type Default Description
|
{Number} |
0 |
Only assets bigger than this size are processed (in bytes) |
Name Type Default Description
|
{Number} |
0.8 |
Only assets that compress better than this ratio are processed (
minRatio = Compressed Size / Original Size
) |
Name Type Default Description
|
{String\|Function} |
[path][base].gz |
The target asset filename |
Name Type Default Description
|
{Boolean\|'keep-source-map'} |
false |
Whether to delete the original assets or not |
test
Type: String|RegExp|Array<String|RegExp>
Default: undefined
Include all assets that pass test assertion.
webpack.config.js
module.exports = {
plugins: [
new CompressionPlugin({
test: /\.js(\?.*)?$/i,
}),
],
};
include
Type: String|RegExp|Array<String|RegExp>
Default: undefined
Include all assets matching any of these conditions.
webpack.config.js
module.exports = {
plugins: [
new CompressionPlugin({
include: /\/includes/,
}),
],
};
exclude
Type: String|RegExp|Array<String|RegExp>
Default: undefined
Exclude all assets matching any of these conditions.
webpack.config.js
module.exports = {
plugins: [
new CompressionPlugin({
exclude: /\/excludes/,
}),
],
};
algorithm
Type: String|Function
Default: gzip
The compression algorithm/function.
ℹ️ If you use custom function for the
algorithm
option, the default value of thecompressionOptions
option is{}
.
String
The algorithm is taken from zlib.
webpack.config.js
module.exports = {
plugins: [
new CompressionPlugin({
algorithm: "gzip",
}),
],
};
Function
Allow to specify a custom compression function.
webpack.config.js
module.exports = {
plugins: [
new CompressionPlugin({
algorithm(input, compressionOptions, callback) {
return compressionFunction(input, compressionOptions, callback);
},
}),
],
};
compressionOptions
Type: Object
Default: { level: 9 }
Compression options for algorithm
.
You can find all options here zlib.
ℹ️ If you use custom function for the
algorithm
option, the default value is{}
.
webpack.config.js
module.exports = {
plugins: [
new CompressionPlugin({
compressionOptions: { level: 1 },
}),
],
};
threshold
Type: Number
Default: 0
Only assets bigger than this size are processed. In bytes.
webpack.config.js
module.exports = {
plugins: [
new CompressionPlugin({
threshold: 8192,
}),
],
};
minRatio
Type: Number
Default: 0.8
Only assets that compress better than this ratio are processed (minRatio = Compressed Size / Original Size
).
Example: you have image.png
file with 1024b size, compressed version of file has 768b size, so minRatio
equal 0.75
.
In other words assets will be processed when the Compressed Size / Original Size
value less minRatio
value.
You can use 1
value to process assets that are smaller than the original.
Use a value of Infinity
to process all assets even if they are larger than the original size or their original size is 0
bytes (useful when you are pre-zipping all assets for AWS).
Use a value of Number.MAX_SAFE_INTEGER
to process all assets even if they are larger than the original size, excluding assets with their original size is 0
bytes.
webpack.config.js
module.exports = {
plugins: [
new CompressionPlugin({
// Compress all assets, including files with `0` bytes size
// minRatio: Infinity
// Compress all assets, excluding files with `0` bytes size
// minRatio: Number.MAX_SAFE_INTEGER
minRatio: 0.8,
}),
],
};
filename
Type: String|Function
Default: "[path][base].gz"
The target asset filename.
String
For example we have assets/images/image.png?foo=bar#hash
:
[path]
is replaced with the directories to the original asset, included trailing /
(assets/images/
).
[file]
is replaced with the path of original asset (assets/images/image.png
).
[base]
is replaced with the base ([name]
+ [ext]
) of the original asset (image.png
).
[name]
is replaced with the name of the original asset (image
).
[ext]
is replaced with the extension of the original asset, included .
(.png
).
[query]
is replaced with the query of the original asset, included ?
(?foo=bar
).
[fragment]
is replaced with the fragment (in the concept of URL it is called hash
) of the original asset (#hash
).
webpack.config.js
module.exports = {
plugins: [
new CompressionPlugin({
filename: "[path][base].gz",
}),
],
};
Function
webpack.config.js
module.exports = {
plugins: [
new CompressionPlugin({
filename(pathData) {
// The `pathData` argument contains all placeholders - `path`/`name`/`ext`/etc
// Available properties described above, for the `String` notation
if (/\.svg$/.test(pathData.filename)) {
return "assets/svg/[path][base].gz";
}
return "assets/js/[path][base].gz";
},
}),
],
};
deleteOriginalAssets
Type: Boolean | 'keep-source-map'
Default: false
Whether to delete the original assets or not.
webpack.config.js
module.exports = {
plugins: [
new CompressionPlugin({
deleteOriginalAssets: true,
}),
],
};
To exclude sourcemaps from compression
module.exports = {
plugins: [
new CompressionPlugin({
exclude: /.map$/
deleteOriginalAssets: 'keep-source-map',
}),
],
};
Prepare compressed versions of assets using zopfli
library.
ℹ️
@gfx/zopfli
require minimum8
version ofnode
.
To begin, you'll need to install @gfx/zopfli
:
$ npm install @gfx/zopfli --save-dev
webpack.config.js
const zopfli = require("@gfx/zopfli");
module.exports = {
plugins: [
new CompressionPlugin({
compressionOptions: {
numiterations: 15,
},
algorithm(input, compressionOptions, callback) {
return zopfli.gzip(input, compressionOptions, callback);
},
}),
],
};
Brotli is a compression algorithm originally developed by Google, and offers compression superior to gzip.
Node 10.16.0 and later has native support for Brotli compression in its zlib module.
We can take advantage of this built-in support for Brotli in Node 10.16.0 and later by just passing in the appropriate algorithm
to the CompressionPlugin:
webpack.config.js
const zlib = require("zlib");
module.exports = {
plugins: [
new CompressionPlugin({
filename: "[path][base].br",
algorithm: "brotliCompress",
test: /\.(js|css|html|svg)$/,
compressionOptions: {
params: {
[zlib.constants.BROTLI_PARAM_QUALITY]: https://github.com/webpack-contrib/compression-webpack-plugin/blob/master/11,
},
},
threshold: 10240,
minRatio: 0.8,
deleteOriginalAssets: false,
}),
],
};
Note Brotli’s BROTLI_PARAM_QUALITY
option is functionally equivalent to zlib’s level
option.
You can find all Brotli’s options in the relevant part of the zlib module documentation.
webpack.config.js
const zlib = require("zlib");
module.exports = {
plugins: [
new CompressionPlugin({
filename: "[path][base].gz",
algorithm: "gzip",
test: /\.js$|\.css$|\.html$/,
threshold: 10240,
minRatio: 0.8,
}),
new CompressionPlugin({
filename: "[path][base].br",
algorithm: "brotliCompress",
test: /\.(js|css|html|svg)$/,
compressionOptions: {
params: {
[zlib.constants.BROTLI_PARAM_QUALITY]: https://github.com/webpack-contrib/compression-webpack-plugin/blob/master/11,
},
},
threshold: 10240,
minRatio: 0.8,
}),
],
};
Please take a moment to read our contributing guidelines if you haven't yet done so.
Context refers to a require with an expression such as require('./locale/' + name + '.json')
. When encountering such an expression, webpack infers the directory ('./locale/'
) and a regular expression (/^.*\.json$/
). Since the name
is not known at compile time, webpack includes every file as module in the bundle.
The ContextReplacementPlugin
allows you to override the inferred information. There are various ways to configure the plugin:
new webpack.ContextReplacementPlugin(
resourceRegExp: RegExp,
newContentResource?: string,
newContentRecursive?: boolean,
newContentRegExp?: RegExp
)
If the resource (directory) matches resourceRegExp
, the plugin replaces the default resource, recursive flag or generated regular expression with newContentResource
, newContentRecursive
or newContextRegExp
respectively. If newContentResource
is relative, it is resolved relative to the previous resource.
Here's a small example to restrict module usage:
new webpack.ContextReplacementPlugin(
/moment[/\\]locale$/,
/de|fr|hu/
);
The moment/locale
context is restricted to files matching /de|fr|hu/
. Thus only those locales are included (see this issue for more information).
new webpack.ContextReplacementPlugin(
resourceRegExp: RegExp,
newContentCallback: (data) => void
);
The newContentCallback
function is given a data
object of the ContextModuleFactory
and is expected to overwrite the request
attribute of the supplied object.
Using this callback we can dynamically redirect requests to a new location:
new webpack.ContextReplacementPlugin(/^\.\/locale$/, (context) => {
if ( !/\/moment\//.test(context.context) ) return;
Object.assign(context, {
regExp: /^\.\/\w+/,
request: '../../locale' // resolved relatively
});
});
The newContentResource
and newContentCreateContextMap
parameters are also available:
new webpack.ContextReplacementPlugin(
resourceRegExp: RegExp,
newContentResource: string,
newContentCreateContextMap: object // mapping runtime-request (userRequest) to compile-time-request (request)
);
These two parameters can be used together to redirect requests in a more targeted way. The newContentCreateContextMap
allows you to map runtime requests to compile requests in the form of an object:
new ContextReplacementPlugin(/selector/, './folder', {
'./request': './request',
'./other-request': './new-request'
});
Copies individual files or entire directories, which already exist, to the build directory.
To begin, you'll need to install copy-webpack-plugin
:
npm install copy-webpack-plugin --save-dev
Then add the plugin to your webpack
config. For example:
webpack.config.js
const CopyPlugin = require("copy-webpack-plugin");
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{ from: "source", to: "dest" },
{ from: "other", to: "public" },
],
}),
],
};
ℹ️
copy-webpack-plugin
is not designed to copy files generated from the build process; rather, it is to copy files that already exist in the source tree, as part of the build process.ℹ️ If you want
webpack-dev-server
to write files to the output directory during development, you can force it with thewriteToDisk
option or thewrite-file-webpack-plugin
.ℹ️ You can get the original source filename from Asset Objects.
Name | Type | Description |
---|---|---|
Name Type Description
|
{Array<String\|Object>} |
Specify file related patterns for plugin |
Name Type Description
|
{Object} |
Specify options for plugin |
The plugin's signature:
webpack.config.js
const CopyPlugin = require("copy-webpack-plugin");
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{ from: "source", to: "dest" },
{ from: "other", to: "public" },
],
options: {
concurrency: 100,
},
}),
],
};
Name | Type | Default | Description |
---|---|---|---|
Name Type Default Description
|
{String} |
undefined |
Glob or path from where we copy files. |
Name Type Default Description
|
{String\|Function} |
compiler.options.output |
Output path. |
Name Type Default Description
|
{String} |
options.context \|\| compiler.options.context |
A path that determines how to interpret the
from
path. |
Name Type Default Description
|
{Object} |
undefined |
Options
passed to the glob pattern matching library including
ignore
option. |
Name Type Default Description
|
{Function} |
undefined |
Allows to filter copied assets. |
Name Type Default Description
|
{String} |
undefined |
Determinate what is
to
option - directory, file or template. |
Name Type Default Description
|
{Boolean} |
false |
Overwrites files already in
compilation.assets
(usually added by other plugins/loaders). |
Name Type Default Description
|
{Number} |
0 |
Allows you to specify the copy priority. |
Name Type Default Description
|
{Object} |
undefined |
Allows to modify the file contents. Enable
transform
caching. You can use
{ transform: {cache: { key: 'my-cache-key' }} }
to invalidate the cache. |
Name Type Default Description
|
{Function} |
undefined |
Allows you to modify the contents of multiple files and save the result to one file. |
Name Type Default Description
|
{Boolean} |
false |
Doesn't generate an error on missing file(s). |
Name Type Default Description
|
{Object\|Function} |
undefined |
Allows to add assets info. |
from
Type: String
Default: undefined
Glob or path from where we copy files.
Globs accept fast-glob pattern-syntax.
Glob can only be a string
.
⚠️ Don't use directly
\\
infrom
option if it is aglob
(i.epath\to\file.ext
) option because on UNIX the backslash is a valid character inside a path component, i.e., it's not a separator. On Windows, the forward slash and the backward slash are both separators. Instead please use/
.
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
"relative/path/to/file.ext",
"relative/path/to/dir",
path.resolve(__dirname, "src", "file.ext"),
path.resolve(__dirname, "src", "dir"),
"**/*",
{
from: "**/*",
},
// If absolute path is a `glob` we replace backslashes with forward slashes, because only forward slashes can be used in the `glob`
path.posix.join(
path.resolve(__dirname, "src").replace(/\\/g, "/"),
"*.txt"
),
],
}),
],
};
For windows
If you define from
as absolute file path or absolute folder path on Windows
, you can use windows path segment (\\
)
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: path.resolve(__dirname, "file.txt"),
},
],
}),
],
};
But you should always use forward-slashes in glob
expressions
See fast-glob manual.
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
// If absolute path is a `glob` we replace backslashes with forward slashes, because only forward slashes can be used in the `glob`
from: path.posix.join(
path.resolve(__dirname, "fixtures").replace(/\\/g, "/"),
"*.txt"
),
},
],
}),
],
};
The context
behaves differently depending on what the from
is (glob
, file
or dir
).
More examples
to
Type: String|Function
Default: compiler.options.output
Output path.
⚠️ Don't use directly
\\
into
(i.epath\to\dest
) option because on UNIX the backslash is a valid character inside a path component, i.e., it's not a separator. On Windows, the forward slash and the backward slash are both separators. Instead please use/
orpath
methods.
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "**/*",
to: "relative/path/to/dest/",
},
{
from: "**/*",
to: "/absolute/path/to/dest/",
},
{
from: "**/*",
to: "[path][name].[contenthash][ext]",
},
],
}),
],
};
Allows to modify the writing path.
⚠️ Don't return directly
\\
into
(i.epath\to\newFile
) option because on UNIX the backslash is a valid character inside a path component, i.e., it's not a separator. On Windows, the forward slash and the backward slash are both separators. Instead please use/
orpath
methods.
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "src/*.png",
to({ context, absoluteFilename }) {
return "dest/newPath/[name][ext]";
},
},
],
}),
],
};
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "src/*.png",
to({ context, absoluteFilename }) {
return Promise.resolve("dest/newPath/[name][ext]");
},
},
],
}),
],
};
context
Type: String
Default: options.context|compiler.options.context
A path that determines how to interpret the from
path.
⚠️ Don't use directly
\\
incontext
(i.epath\to\context
) option because on UNIX the backslash is a valid character inside a path component, i.e., it's not a separator. On Windows, the forward slash and the backward slash are both separators. Instead please use/
orpath
methods.
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "src/*.txt",
to: "dest/",
context: "app/",
},
],
}),
],
};
The context
option can be an absolute or relative path. If context
is a relative, then it is converted to absolute based to compiler.options.context
Also, context
indicates how to interpret the search results. Further, he is considered in this role.
To determine the structure from which the found resources will be copied to the destination folder, the context
option is used.
If from
is a file, then context
is equal to the directory in which this file is located. Accordingly, the result will be only the file name.
If from
is a directory, then context
is the same as from
and is equal to the directory itself. In this case, the result will be a hierarchical structure of the found folders and files relative to the specified directory.
If from
is a glob, then regardless of the context
option, the result will be the structure specified in the from
option
More examples
globOptions
Type: Object
Default: undefined
Allows to configute the glob pattern matching library used by the plugin. See the list of supported options To exclude files from the selection, you should use globOptions.ignore option
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "public/**/*",
globOptions: {
dot: true,
gitignore: true,
ignore: ["**/file.*", "**/ignored-directory/**"],
},
},
],
}),
],
};
filter
Type: Function
Default: undefined
ℹ️ To ignore files by path please use the
globOptions.ignore
option.
webpack.config.js
const fs = require("fs").promise;
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "public/**/*",
filter: async (resourcePath) => {
const data = await fs.promises.readFile(resourcePath);
const content = data.toString();
if (content === "my-custom-content") {
return false;
}
return true;
},
},
],
}),
],
};
toType
Type: String
Default: undefined
Determinate what is to
option - directory, file or template.
Sometimes it is hard to say what is to
, example path/to/dir-with.ext
.
If you want to copy files in directory you need use dir
option.
We try to automatically determine the type
so you most likely do not need this option.
Name | Type | Default | Description |
---|---|---|---|
Name Type Default Description
|
{String} |
undefined |
If
to
has no extension or ends on
'/' |
Name Type Default Description
|
{String} |
undefined |
If
to
is not a directory and is not a template |
Name Type Default Description
|
{String} |
undefined |
If
to
contains
a template pattern |
'dir'
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "path/to/file.txt",
to: "directory/with/extension.ext",
toType: "dir",
},
],
}),
],
};
'file'
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "path/to/file.txt",
to: "file/without/extension",
toType: "file",
},
],
}),
],
};
'template'
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "src/",
to: "dest/[name].[contenthash][ext]",
toType: "template",
},
],
}),
],
};
force
Type: Boolean
Default: false
Overwrites files already in compilation.assets
(usually added by other plugins/loaders).
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "src/**/*",
to: "dest/",
force: true,
},
],
}),
],
};
priority
Type: Number
Default: 0
Allows to specify the priority of copying files with the same destination name.
Files for patterns with higher priority will be copied later.
To overwrite files, the force
option must be enabled.
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
// Copied second and will overwrite "dir_2/file.txt"
{
from: "dir_1/file.txt",
to: "newfile.txt",
force: true,
priority: 10,
},
// Copied first
{
from: "dir_2/file.txt",
to: "newfile.txt",
priority: 5,
},
],
}),
],
};
transform
Type: Function|Object
Default: undefined
Allows to modify the file contents.
Function
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "src/*.png",
to: "dest/",
// The `content` argument is a [`Buffer`](https://nodejs.org/api/buffer.html) object, it could be converted to a `String` to be processed using `content.toString()`
// The `absoluteFrom` argument is a `String`, it is absolute path from where the file is being copied
transform(content, absoluteFrom) {
return optimize(content);
},
},
],
}),
],
};
Object
Name | Type | Default | Description |
---|---|---|---|
Name Type Default Description
|
{Function} |
undefined |
Allows to modify the file contents. |
Name Type Default Description
|
{Boolean\|Object} |
false |
Enable
transform
caching. You can use
transform: { cache: { key: 'my-cache-key' } }
to invalidate the cache. |
transformer
Type: Function
Default: undefined
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "src/*.png",
to: "dest/",
// The `content` argument is a [`Buffer`](https://nodejs.org/api/buffer.html) object, it could be converted to a `String` to be processed using `content.toString()`
// The `absoluteFrom` argument is a `String`, it is absolute path from where the file is being copied
transform: {
transformer(content, absoluteFrom) {
return optimize(content);
},
},
},
],
}),
],
};
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "src/*.png",
to: "dest/",
transform: {
transformer(content, path) {
return Promise.resolve(optimize(content));
},
},
},
],
}),
],
};
cache
Type: Boolean|Object
Default: false
webpack.config.js
Enable/disable and configure caching.
Default path to cache directory: node_modules/.cache/copy-webpack-plugin
.
Boolean
Enables/Disable transform
caching.
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "src/*.png",
to: "dest/",
transform: {
transformer(content, path) {
return optimize(content);
},
cache: true,
},
},
],
}),
],
};
Object
Enables transform
caching and setup cache directory and invalidation keys.
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "src/*.png",
to: "dest/",
transform: {
transformer(content, path) {
return optimize(content);
},
cache: {
directory: path.resolve(__dirname, "cache-directory"),
keys: {
// May be useful for invalidating cache based on external values
// For example, you can invalid cache based on `process.version` - { node: process.version }
key: "value",
},
},
},
},
],
}),
],
};
You can setup invalidation keys using a function.
Simple function:
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "src/*.png",
to: "dest/",
transform: {
transformer(content, path) {
return optimize(content);
},
cache: {
directory: path.resolve(__dirname, "cache-directory"),
keys: (defaultCacheKeys, absoluteFrom) => {
const keys = getCustomCacheInvalidationKeysSync();
return {
...defaultCacheKeys,
keys,
};
},
},
},
},
],
}),
],
};
Async function:
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "src/*.png",
to: "dest/",
transform: {
transformer(content, path) {
return optimize(content);
},
cache: {
directory: path.resolve(__dirname, "cache-directory"),
keys: async (defaultCacheKeys, absoluteFrom) => {
const keys = await getCustomCacheInvalidationKeysAsync();
return {
...defaultCacheKeys,
keys,
};
},
},
},
},
],
}),
],
};
transformAll
Type: Function
Default: undefined
Allows you to modify the contents of multiple files and save the result to one file.
ℹ️ The
to
option must be specified and point to a file. It is allowed to use only[contenthash]
and[fullhash]
template strings.
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "src/**/*.txt",
to: "dest/file.txt",
// The `assets` argument is an assets array for the pattern.from ("src/**/*.txt")
transformAll(assets) {
const result = assets.reduce((accumulator, asset) => {
// The asset content can be obtained from `asset.source` using `source` method.
// The asset content is a [`Buffer`](https://nodejs.org/api/buffer.html) object, it could be converted to a `String` to be processed using `content.toString()`
const content = asset.data;
accumulator = `${accumulator}${content}\n`;
return accumulator;
}, "");
return result;
},
},
],
}),
],
};
noErrorOnMissing
Type: Boolean
Default: false
Doesn't generate an error on missing file(s).
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: path.resolve(__dirname, "missing-file.txt"),
noErrorOnMissing: true,
},
],
}),
],
};
info
Type: Object|Function<Object>
Default: undefined
Allows to add assets info.
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
"relative/path/to/file.ext",
{
from: "**/*",
// Terser skip this file for minimization
info: { minimized: true },
},
],
}),
],
};
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
"relative/path/to/file.ext",
{
from: "**/*",
// Terser skip this file for minimization
info: (file) => ({ minimized: true }),
},
],
}),
],
};
Name | Type | Default | Description |
---|---|---|---|
Name Type Default Description
|
{Number} |
100 |
Limits the number of simultaneous requests to fs |
concurrency
limits the number of simultaneous requests to fs
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [...patterns],
options: { concurrency: 50 },
}),
],
};
from
(glob
, file
or dir
).Take for example the following file structure:
src/directory-nested/deep-nested/deepnested-file.txt
src/directory-nested/nested-file.txt
Everything that you specify in from
will be included in the result:
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "src/directory-nested/**/*",
},
],
}),
],
};
Result:
src/directory-nested/deep-nested/deepnested-file.txt,
src/directory-nested/nested-file.txt
If you want only content src/directory-nested/
, you should only indicate glob
in from
. The path to the folder in which the search should take place, should be moved to context
.
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "**/*",
context: path.resolve(__dirname, "src", "directory-nested"),
},
],
}),
],
};
Result:
deep-nested/deepnested-file.txt,
nested-file.txt
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: path.resolve(__dirname, "src", "directory-nested"),
},
],
}),
],
};
Result:
deep-nested/deepnested-file.txt,
nested-file.txt
Technically, this is **/*
with a predefined context equal to the specified directory.
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "**/*",
context: path.resolve(__dirname, "src", "directory-nested"),
},
],
}),
],
};
Result:
deep-nested/deepnested-file.txt,
nested-file.txt
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: path.resolve(
__dirname,
"src",
"directory-nested",
"nested-file.txt"
),
},
],
}),
],
};
Result:
nested-file.txt
Technically, this is a filename with a predefined context equal to path.dirname(pathToFile)
.
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "nested-file.txt",
context: path.resolve(__dirname, "src", "directory-nested"),
},
],
}),
],
};
Result:
nested-file.txt
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: path.posix.join(
path.resolve(__dirname, "src").replace(/\\/g, "/"),
"**/*"
),
globOptions: {
ignore: [
// Ignore all `txt` files
"**/*.txt",
// Ignore all files in all subdirectories
"**/subdir/**",
],
},
},
],
}),
],
};
Removes all directory references and only copies file names.
⚠️ If files have the same name, the result is non-deterministic.
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: "src/**/*",
to: "[name][ext]",
},
],
}),
],
};
Result:
file-1.txt
file-2.txt
nested-file.txt
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
// When copying files starting with a dot, must specify the toType option
// toType: "file",
to({ context, absoluteFilename }) {
return `newdirectory/${path.relative(context, absoluteFilename)}`;
},
from: "directory",
},
],
}),
],
};
Result:
"newdirectory/file-1.txt",
"newdirectory/nestedfile.txt",
"newdirectory/nested/deep-nested/deepnested.txt",
"newdirectory/nested/nestedfile.txt",
Useful if you need to simply copy *.js
files to destination "as is" without evaluating and minimizing them using Terser.
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
"relative/path/to/file.ext",
{
from: "**/*",
// Terser skip this file for minimization
info: { minimized: true },
},
],
}),
],
};
yarn workspaces
and monorepos
When using yarn workspaces
ormonorepos
, relative copy paths from node_modules can be broken due to the way packages are hoisting.
To avoid this, should explicitly specify where to copy the files from using require.resolve
.
webpack.config.js
module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: `${path.dirname(
require.resolve(`${moduleName}/package.json`)
)}/target`,
to: "target",
},
],
}),
],
};
Please take a moment to read our contributing guidelines if you haven't yet done so.
The DefinePlugin
allows you to create global constants which can be configured at compile time. This can be useful for allowing different behavior between development builds and production builds. If you perform logging in your development build but not in the production build you might use a global constant to determine whether logging takes place. That's where DefinePlugin
shines, set it and forget it rules for development and production builds.
new webpack.DefinePlugin({
// Definitions...
});
Each key passed into DefinePlugin
is an identifier or multiple identifiers joined with .
.
typeof
to the key, it's only defined for typeof calls.The values will be inlined into the code allowing a minification pass to remove the redundant conditional.
new webpack.DefinePlugin({
PRODUCTION: JSON.stringify(true),
VERSION: JSON.stringify('5fa3b9'),
BROWSER_SUPPORTS_HTML5: true,
TWO: '1+1',
'typeof window': JSON.stringify('object'),
'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV)
});
console.log('Running App version ' + VERSION);
if(!BROWSER_SUPPORTS_HTML5) require('html5shiv');
When defining values for
process
prefer'process.env.NODE_ENV': JSON.stringify('production')
overprocess: { env: { NODE_ENV: JSON.stringify('production') } }
. Using the latter will overwrite theprocess
object which can break compatibility with some modules that expect other values on the process object to be defined.
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 usingJSON.stringify('production')
.
index.js
if (!PRODUCTION) {
console.log('Debug info');
}
if (PRODUCTION) {
console.log('Production log');
}
After passing through webpack with no minification results in:
if (!true) {
console.log('Debug info');
}
if (true) {
console.log('Production log');
}
and then after a minification pass results in:
console.log('Production log');
Enable/disable features in production/development build using feature flags.
new webpack.DefinePlugin({
'NICE_FEATURE': JSON.stringify(true),
'EXPERIMENTAL_FEATURE': JSON.stringify(false)
});
Use a different service URL in production/development builds:
new webpack.DefinePlugin({
'SERVICE_URL': JSON.stringify('https://dev.example.com')
});
The DllPlugin
and DllReferencePlugin
provide means to split bundles in a way that can drastically improve build time performance. The term "DLL" stands for Dynamic-link library which was originally introduced by Microsoft.
DllPlugin
This plugin 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
to map dependencies.
context
(optional): context of requests in the manifest file (defaults to the webpack context.)name
: name of the exposed dll function (TemplatePaths: [hash]
& [name]
)path
: absolute path to the manifest json file (output)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
.
Combine this plugin with output.library
option to expose (aka, put into the global scope) the dll function.
DllReferencePlugin
This plugin is used in the primary webpack config, it references the dll-only-bundle(s) to require pre-built dependencies.
context
: (absolute path) context of requests in the manifest (or content property)manifest
: an object containing content
and name
or a string to the absolute path of the JSON manifest to be loaded upon compilationcontent
(optional): the mappings from request to module id (defaults to manifest.content
)name
(optional): an identifier where the dll is exposed (defaults to manifest.name
) (see also externals
)scope
(optional): prefix which is used for accessing the content of the dllsourceType
(optional): how the dll is exposed (libraryTarget)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.
Keep the
name
consistent withoutput.library
.
This plugin can be used in two different modes, scoped and mapped.
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')
.
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.
DllReferencePlugin
andDllPlugin
are used in separate webpack configs.
webpack.vendor.config.js
new webpack.DllPlugin({
context: __dirname,
name: '[name]_[hash]',
path: path.join(__dirname, 'manifest.json'),
});
webpack.app.config.js
new webpack.DllReferencePlugin({
context: __dirname,
manifest: require('./manifest.json'),
scope: 'xyz',
sourceType: 'commonjs2'
});
Two separate example folders. Demonstrates scope and context.
Multiple
DllPlugins
and multipleDllReferencePlugins
.
The EnvironmentPlugin
is shorthand for using the DefinePlugin
on process.env
keys.
The EnvironmentPlugin
accepts either an array of keys or an object mapping its keys to their default values.
new webpack.EnvironmentPlugin(['NODE_ENV', 'DEBUG']);
This is equivalent to the following DefinePlugin
application:
new webpack.DefinePlugin({
'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
'process.env.DEBUG': JSON.stringify(process.env.DEBUG)
});
Not specifying the environment variable raises an "
EnvironmentPlugin
-${key}
environment variable is undefined" error.
Alternatively, the EnvironmentPlugin
supports an object, which maps keys to their default values. The default value for a key is taken if the key is undefined in process.env
.
new webpack.EnvironmentPlugin({
NODE_ENV: 'development', // use 'development' unless process.env.NODE_ENV is defined
DEBUG: false
});
Variables coming from
process.env
are always strings.
Unlike
DefinePlugin
, default values are applied toJSON.stringify
by theEnvironmentPlugin
.
To specify an unset default value, use
null
instead ofundefined
.
Example:
Let's investigate the result when running the previous EnvironmentPlugin
configuration on a test file entry.js
:
if (process.env.NODE_ENV === 'production') {
console.log('Welcome to production');
}
if (process.env.DEBUG) {
console.log('Debugging output');
}
When executing NODE_ENV=production webpack
in the terminal to build, entry.js
becomes this:
if ('production' === 'production') { // <-- 'production' from NODE_ENV is taken
console.log('Welcome to production');
}
if (false) { // <-- default value is taken
console.log('Debugging output');
}
Running DEBUG=false webpack
yields:
if ('development' === 'production') { // <-- default value is taken
console.log('Welcome to production');
}
if ('false') { // <-- 'false' from DEBUG is taken
console.log('Debugging output');
}
DotenvPlugin
The third-party DotenvPlugin
(dotenv-webpack
) allows you to expose (a subset of) dotenv variables:
// .env
DB_HOST=127.0.0.1
DB_PASS=foobar
S3_API=mysecretkey
new Dotenv({
path: './.env', // Path to .env file (this is the default)
safe: true // load .env.example (defaults to "false" which does not use dotenv-safe)
});
This plugin enables more fine grained control of source map generation. It is also enabled automatically by certain settings of the devtool
configuration option.
new webpack.EvalSourceMapDevToolPlugin(options);
The following options are supported:
test
(string|regex|array
): Include source maps for modules based on their extension (defaults to .js
and .css
).include
(string|regex|array
): Include source maps for module paths that match the given value.exclude
(string|regex|array
): Exclude modules that match the given value from source map generation.filename
(string
): Defines the output filename of the SourceMap (will be inlined if no value is provided).append
(string
): Appends the given value to the original asset. Usually the #sourceMappingURL
comment. [url]
is replaced with a URL to the source map file. false
disables the appending.moduleFilenameTemplate
(string
): See output.devtoolModuleFilenameTemplate
.module
(boolean
): Indicates whether loaders should generate source maps (defaults to true
).columns
(boolean
): Indicates whether column mappings should be used (defaults to true
).protocol
(string
): Allows user to override default protocol (webpack-internal://
)Setting
module
and/orcolumns
tofalse
will yield less accurate source maps but will also improve compilation performance significantly.
If you want to use a custom configuration for this plugin in development mode, make sure to disable the default one. I.e. set
devtool: false
.
The following examples demonstrate some common use cases for this plugin.
You can use the following code to replace the configuration option devtool: eval-source-map
with an equivalent custom plugin configuration:
module.exports = {
// ...
devtool: false,
plugins: [
new webpack.EvalSourceMapDevToolPlugin({})
]
};
The following code would exclude source maps for any modules in the vendor.js
bundle:
new webpack.EvalSourceMapDevToolPlugin({
filename: '[name].js.map',
exclude: ['vendor.js']
});
The ExtendedAPIPlugin
adds two free variables to the compilation, which adds the global hash to the runtime.
__webpack_hash__
: The hash of chunk__webpack_chunkname__
: The name of chunkDon't combine
ExtendedAPIPlugin
with theHotModuleReplacementPlugin
to avoid conflicts, they both add hashes to runtime.
Don't combine
ExtendedAPIPlugin
with the usage of[chunkhash]
or[contenthash]
in output configuration. See this pull request for details.
new webpack.ExtendedAPIPlugin();
Extract text from a bundle, or bundles, into a separate file.
npm install --save-dev extract-text-webpack-plugin
# for webpack 2
npm install --save-dev extract-text-webpack-plugin@2.1.2
# for webpack 1
npm install --save-dev extract-text-webpack-plugin@1.0.1
:warning: Since webpack v4 the
extract-text-webpack-plugin
should not be used for css. Use mini-css-extract-plugin instead.:warning: For webpack v1, see the README in the webpack-1 branch.
const ExtractTextPlugin = require("extract-text-webpack-plugin");
module.exports = {
module: {
rules: [
{
test: /\.css$/,
use: ExtractTextPlugin.extract({
fallback: "style-loader",
use: "css-loader"
})
}
]
},
plugins: [
new ExtractTextPlugin("styles.css"),
]
}
It moves all the required *.css
modules in entry chunks into a separate CSS file. So your styles are no longer inlined into the JS bundle, but in a separate CSS file (styles.css
). If your total stylesheet volume is big, it will be faster because the CSS bundle is loaded in parallel to the JS bundle.
Advantages | Caveats |
---|---|
Advantages Caveats Fewer style tags (older IE has a limit) Additional HTTP request |
Additional HTTP request |
Advantages Caveats CSS SourceMap (with Longer compilation time |
Longer compilation time |
Advantages Caveats CSS requested in parallel No runtime public path modification |
No runtime public path modification |
Advantages Caveats CSS cached separate No Hot Module Replacement |
No Hot Module Replacement |
Advantages Caveats Faster runtime (less code and DOM operations) ... |
... |
new ExtractTextPlugin(options: filename | object)
Name | Type | Description |
---|---|---|
Name Type Description
|
{String} |
Unique ident for this plugin instance. (For advanced usage only, by default automatically generated) |
Name Type Description
|
{String\|Function} |
Name of the result file. May contain
[name]
,
[id]
and
[contenthash] |
Name Type Description
|
{Boolean} |
Extract from all additional chunks too (by default it extracts only from the initial chunk(s))
When using CommonsChunkPlugin
and there are extracted chunks (from
ExtractTextPlugin.extract
) in the commons chunk,
allChunks
must
be set to
true |
Name Type Description
|
{Boolean} |
Disables the plugin |
Name Type Description
|
{Boolean} |
Disables order check (useful for CSS Modules!),
false
by default |
[name]
name of the chunk[id]
number of the chunk[contenthash]
hash of the content of the extracted file[<hashType>:contenthash:<digestType>:<length>]
optionally you can configure
hashType
s, e.g. sha1
, md5
, sha256
, sha512
digestType
s, e.g. hex
, base26
, base32
, base36
, base49
, base52
, base58
, base62
, base64
length
, the length of the hash in chars:warning:
ExtractTextPlugin
generates a file per entry, so you must use[name]
,[id]
or[contenthash]
when using multiple entries.
#extract
ExtractTextPlugin.extract(options: loader | object)
Creates an extracting loader from an existing loader. Supports loaders of type { loader: [name]-loader -> {String}, options: {} -> {Object} }
.
Name | Type | Description |
---|---|---|
Name Type Description
|
{String}
/
{Array}
/
{Object} |
Loader(s) that should be used for converting the resource to a CSS exporting module (required) |
Name Type Description
|
{String}
/
{Array}
/
{Object} |
loader(e.g
'style-loader'
) that should be used when the CSS is not extracted (i.e. in an additional chunk when
allChunks: false
) |
Name Type Description
|
{String} |
Override the
publicPath
setting for this loader |
There is also an extract
function on the instance. You should use this if you have more than one instance of ExtractTextPlugin
.
const ExtractTextPlugin = require('extract-text-webpack-plugin');
// Create multiple instances
const extractCSS = new ExtractTextPlugin('stylesheets/[name]-one.css');
const extractLESS = new ExtractTextPlugin('stylesheets/[name]-two.css');
module.exports = {
module: {
rules: [
{
test: /\.css$/,
use: extractCSS.extract([ 'css-loader', 'postcss-loader' ])
},
{
test: /\.less$/i,
use: extractLESS.extract([ 'css-loader', 'less-loader' ])
},
]
},
plugins: [
extractCSS,
extractLESS
]
};
The configuration is the same, switch out sass-loader
for less-loader
when necessary.
const ExtractTextPlugin = require('extract-text-webpack-plugin');
module.exports = {
module: {
rules: [
{
test: /\.scss$/,
use: ExtractTextPlugin.extract({
fallback: 'style-loader',
use: ['css-loader', 'sass-loader']
})
}
]
},
plugins: [
new ExtractTextPlugin('style.css')
//if you want to pass in options, you can do so:
//new ExtractTextPlugin({
// filename: 'style.css'
//})
]
}
url()
ResolvingIf you are finding that urls are not resolving properly when you run webpack. You can expand your loader functionality with options. The url: false
property allows your paths resolved without any changes.
const ExtractTextPlugin = require('extract-text-webpack-plugin');
module.exports = {
module: {
rules: [
{
test: /\.scss$/,
use: ExtractTextPlugin.extract({
fallback: 'style-loader',
use: [
{
loader: 'css-loader',
options: {
// If you are having trouble with urls not resolving add this setting.
// See https://github.com/webpack-contrib/css-loader#url
url: false,
minimize: true,
sourceMap: true
}
},
{
loader: 'sass-loader',
options: {
sourceMap: true
}
}
]
})
}
]
}
}
filename
parameter could be Function
. It passes getPath
to process the format like css/[name].css
and returns the real file name, css/js/a.css
. You can replace css/js
with css
then you will get the new path css/a.css
.
entry: {
'js/a': "./a"
},
plugins: [
new ExtractTextPlugin({
filename: (getPath) => {
return getPath('css/[name].css').replace('css/js', 'css');
},
allChunks: true
})
]
Juho Vepsäläinen | Joshua Wiens | Kees Kluskens | Sean Larkin |
This plugin will cause hashes to be based on the relative path of the module, generating a four character string as the module id. Suggested for use in production.
new webpack.HashedModuleIdsPlugin({
// Options...
});
This plugin supports the following options:
hashFunction
: The hashing algorithm to use, defaults to 'md4'
. All functions from Node.JS' crypto.createHash
are supported.hashDigest
: The encoding to use when generating the hash, defaults to 'base64'
. All encodings from Node.JS' hash.digest
are supported.hashDigestLength
: The prefix length of the hash digest to use, defaults to 4
. Note that some generated ids might be longer than specified here, to avoid module id collisions.Here's an example of how this plugin might be used:
new webpack.HashedModuleIdsPlugin({
hashFunction: 'sha256',
hashDigest: 'hex',
hashDigestLength: 20
});
Enables Hot Module Replacement, otherwise known as HMR.
HMR should never be used in production.
Enabling HMR is easy and in most cases no options are necessary.
new webpack.HotModuleReplacementPlugin({
// Options...
});
The following options are accepted:
multiStep
(boolean): If true
, the plugin will build in two steps -- first compiling the hot update chunks, and then the remaining normal assets.fullBuildTimeout
(number): The delay between the two steps when multiStep
is enabled.requestTimeout
(number): The timeout used for manifest download (since webpack 3.0.0)These options are experimental and may be deprecated. As mentioned above, they are typically not necessary and including a
new webpack.HotModuleReplacementPlugin()
is enough.
The HtmlWebpackPlugin
simplifies creation of HTML files to serve your webpack bundles. This is especially useful for webpack bundles that include a hash in the filename which changes every compilation. You can either let the plugin generate an HTML file for you, supply your own template using lodash templates, or use your own loader.
npm install --save-dev html-webpack-plugin
The plugin will generate an HTML5 file for you that includes all your webpack
bundles in the body using script
tags. Just add the plugin to your webpack
config as follows:
var HtmlWebpackPlugin = require('html-webpack-plugin');
var path = require('path');
module.exports = {
entry: 'index.js',
output: {
path: path.resolve(__dirname, './dist'),
filename: 'index_bundle.js'
},
plugins: [new HtmlWebpackPlugin()]
};
This will generate a file dist/index.html
containing the following:
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>webpack App</title>
</head>
<body>
<script src="index_bundle.js"></script>
</body>
</html>
If you have multiple webpack entry points, they will all be included with <script>
tags in the generated HTML.
If you have any CSS assets in webpack's output (for example, CSS extracted with the MiniCssExtractPlugin) then these will be included with <link>
tags in the <head>
element of generated HTML.
For all configuration options, please see the plugin documentation.
The plugin supports addons. For a list see the documentation.
i18n (localization) plugin for Webpack.
npm i -D i18n-webpack-plugin
This plugin creates bundles with translations baked in. So you can serve the translated bundle to your clients.
see webpack/webpack/examples/i18n.
plugins: [
...
new I18nPlugin(languageConfig, optionsObj)
],
optionsObj.functionName
: the default value is __
, you can change it to other function name.optionsObj.failOnMissing
: the default value is false
, which will show a warning message, if the mapping text cannot be found. If set to true
, the message will be an error message.optionsObj.hideMessage
: the default value is false
, which will show the warning/error message. If set to true
, the message will be hidden.optionsObj.nested
: the default value is false
. If set to true
, the keys in languageConfig
can be nested. This option is interpreted only if languageConfig
isn't a function.Juho Vepsäläinen | Joshua Wiens | Kees Kluskens | Sean Larkin |
IgnorePlugin prevents generation of modules for import
or require
calls matching the regular expressions or filter functions:
resourceRegExp
: A RegExp to test the resource against.contextRegExp
: (optional) A RegExp to test the context (directory) against.new webpack.IgnorePlugin({resourceRegExp, contextRegExp});
// old way, deprecated in webpack v5
new webpack.IgnorePlugin(resourceRegExp, [contextRegExp]);
checkContext(context)
A Filter function that receives context as the argument, must return boolean.checkResource(resource)
A Filter function that receives resource as the argument, must return boolean.new webpack.IgnorePlugin({
checkContext (context) {
// do something with context
return true|false;
},
checkResource (resource) {
// do something with resource
return true|false;
}
});
As of moment 2.18, all locales are bundled together with the core library (see this GitHub issue).
The resourceRegExp
parameter passed to IgnorePlugin
is not tested against the resolved file names or absolute module names being imported or required, but rather against the string passed to require
or import
within the source code where the import is taking place. For example, if you're trying to exclude node_modules/moment/locale/*.js
, this won't work:
-new webpack.IgnorePlugin(/moment\/locale\//);
Rather, because moment
imports with this code:
require('./locale/' + name);
...your first regexp must match that './locale/'
string. The second contextRegExp
parameter is then used to select specific directories from where the import took place. The following will cause those locale files to be ignored:
new webpack.IgnorePlugin({
resourceRegExp: /^\.\/locale$/,
contextRegExp: /moment$/
});
...which means "any require statement matching './locale'
from any directories ending with 'moment'
will be ignored.
This is a list of plugins which are used by webpack internally.
You should only care about them if you are building your own compiler based on webpack, or introspect the internals.
Categories of internal plugins:
Plugins affecting the environment of the compiler.
node/NodeEnvironmentPlugin()
Applies Node.js style filesystem to the compiler.
Plugins affecting the compiler
CachePlugin([cache])
Adds a cache to the compiler, where modules are cached.
You can pass a cache
object, where the modules are cached. Otherwise one is created per plugin instance.
ProgressPlugin(handler)
Hook into the compiler to extract progress information. The handler
must have the signature function(percentage, message)
. Percentage is called with a value between 0 and 1, where 0 indicates the start and 1 the end.
RecordIdsPlugin()
Saves and restores module and chunk ids from records.
Plugins, which add entry chunks to the compilation.
SingleEntryPlugin(context, request, chunkName)
Adds an entry chunk on compilation. The chunk is named chunkName
and contains only one module (plus dependencies). The module is resolved from request
in context
(absolute path).
MultiEntryPlugin(context, requests, chunkName)
Adds an entry chunk on compilation. The chunk is named chunkName
and contains a module for each item in the requests
array (plus dependencies). Each item in requests
is resolved in context
(absolute path).
PrefetchPlugin(context, request)
Prefetches request
and dependencies to enable a more parallel compilation. It doesn't create any chunk. The module is resolved from request
in context
(absolute path).
FunctionModulePlugin(context, options)
Each emitted module is wrapped in a function.
options
are the output options.
If options.pathinfo
is set, each module function is annotated with a comment containing the module identifier shortened to context
(absolute path).
JsonpTemplatePlugin(options)
Chunks are wrapped into JSONP-calls. A loading algorithm is included in entry chunks. It loads chunks by adding a <script>
tag.
options
are the output options.
options.jsonpFunction
is the JSONP function.
options.publicPath
is used as path for loading the chunks.
options.chunkFilename
is the filename under that chunks are expected.
node/NodeTemplatePlugin(options)
Chunks are wrapped into Node.js modules exporting the bundled modules. The entry chunks loads chunks by requiring them.
options
are the output options.
options.chunkFilename
is the filename under that chunks are expected.
LibraryTemplatePlugin(name, target)
The entries chunks are decorated to form a library name
of type type
.
webworker/WebWorkerTemplatePlugin(options)
Chunks are loaded by importScripts
. Else it's similar to JsonpTemplatePlugin
.
options
are the output options.
Decorates the module template by wrapping each module in a eval
annotated with // @sourceURL
.
SourceMapDevToolPlugin(sourceMapFilename, sourceMappingURLComment, moduleFilenameTemplate, fallbackModuleFilenameTemplate)
Decorates the templates by generating a SourceMap for each chunk.
sourceMapFilename
the filename template of the SourceMap. [hash]
, [name]
, [id]
, [file]
and [filebase]
are replaced. If this argument is missing, the SourceMap will be inlined as DataUrl.
NoHotModuleReplacementPlugin()
Defines module.hot
as false
to remove hot module replacement code.
HotModuleReplacementPlugin(options)
Add support for hot module replacement. Decorates the templates to add runtime code. Adds module.hot
API.
options.hotUpdateChunkFilename
the filename for hot update chunks.
options.hotUpdateMainFilename
the filename for the hot update manifest.
options.hotUpdateFunction
JSON function name for the hot update.
Plugins affecting the source code of modules.
Make webpack_public_path, webpack_require, webpack_modules and webpack_chunk_load accessible. Ensures that require.valueOf
and require.onError
are not processed by other plugins.
Currently useless. Ensures compatibility with other module loaders.
Offers a pseudo console
if it is not available.
Tries to evaluate expressions in if (...)
statements and ternaries to replace them with true
/false
for further possible dead branch elimination using hooks fired by the parser.
There are multiple optimizations in production mode regarding dead branches:
webpack will try to evaluate conditional statements. If it succeeds then the dead branch is removed. webpack can't do constant folding unless the compiler knows it. For example:
import { calculateTax } from './tax';
const FOO = 1;
if (FOO === 0) {
// dead branch
calculateTax();
}
In the above example, webpack is unable to prune the branch, but Terser does. However, if FOO
is defined using DefinePlugin, webpack will succeed.
It is important to mention that import { calculateTax } from './tax';
will also get pruned because calculateTax()
call was in the dead branch and got eliminated.
ProvidePlugin(name, request)
If name
is used in a module it is filled by a module loaded by require(<request>)
.
NodeStuffPlugin(options, context)
Provide stuff that is normally available in Node.js modules.
It also ensures that module
is filled with some Node.js stuff if you use it.
Provide stuff that is normally available in require.js.
require[js].config
is removed. require.version
is 0.0.0
. requirejs.onError
is mapped to require.onError
.
node/NodeSourcePlugin(options)
This module adds stuff from Node.js that is not available in non Node.js environments.
It adds polyfills for process
, console
, Buffer
and global
if used. It also binds the built in Node.js replacement modules.
node/NodeTargetPlugin()
The plugins should be used if you run the bundle in a Node.js environment.
If ensures that native modules are loaded correctly even if bundled.
dependencies/AMDPlugin(options)
Provides AMD-style define
and require
to modules. Also bind require.amd
, define.amd
and webpack_amd_options## to the options
passed as parameter.
dependencies/CommonJsPlugin
Provides CommonJs-style require
to modules.
dependencies/LabeledModulesPlugin()
Provide labels require:
and exports:
to modules.
dependencies/RequireContextPlugin(modulesDirectories, extensions)
Provides require.context
. The parameter modulesDirectories
and extensions
are used to find alternative requests for files. It's useful to provide the same arrays as you provide to the resolver.
dependencies/RequireEnsurePlugin()
Provides require.ensure
.
dependencies/RequireIncludePlugin()
Provides require.include
.
DefinePlugin(definitions)
Define constants for identifier.
definitions
is an object.
optimize/LimitChunkCountPlugin(options)
Merge chunks limit chunk count is lower than options.maxChunks
.
The overhead for each chunks is provided by options.chunkOverhead
or defaults to 10000. Entry chunks sizes are multiplied by options.entryChunkMultiplicator
(or 10).
Chunks that reduce the total size the most are merged first. If multiple combinations are equal the minimal merged size wins.
optimize/MergeDuplicateChunksPlugin()
Chunks with the same modules are merged.
optimize/RemoveEmptyChunksPlugin()
Modules that are included in every parent chunk are removed from the chunk.
optimize/MinChunkSizePlugin(minChunkSize)
Merges chunks until each chunk has the minimum size of minChunkSize
.
optimize/FlagIncludedChunksPlugin()
Adds chunk ids of chunks which are included in the chunk. This eliminates unnecessary chunk loads.
optimize/OccurrenceOrderPlugin(preferEntry)
Order the modules and chunks by occurrence. This saves space, because often referenced modules and chunks get smaller ids.
preferEntry
If true, references in entry chunks have higher priority
optimize/DedupePlugin()
Deduplicates modules and adds runtime code.
While writing your code, you may have already added many code split points to load stuff on demand. After compiling you might notice that some chunks are too small - creating larger HTTP overhead. LimitChunkCountPlugin
can post-process your chunks by merging them.
new webpack.optimize.LimitChunkCountPlugin({
// Options...
});
The following options are supported:
maxChunks
number
Limit the maximum number of chunks using a value greater than or equal to 1
. Using 1
will prevent any additional chunks from being added as the entry/main chunk is also included in the count.
webpack.config.js
const webpack = require('webpack');
module.exports = {
// ...
plugins: [
new webpack.optimize.LimitChunkCountPlugin({
maxChunks: 5
})
]
};
minChunkSize
Keeping chunk size above the specified limit is no longer a feature of this plugin. Use [MinChunkSizePlugin)[/plugins/min-chunk-size-plugin] instead.
This plugin and it's options can also be invoked via the CLI:
webpack --optimize-max-chunks 15
The LoaderOptionsPlugin
is unlike other plugins in that it is built for migration from webpack 1 to 2. In webpack 2, the schema for a webpack.config.js
became stricter; no longer open for extension by other loaders and plugins. The intention is that you pass options
directly to loaders and plugins (i.e. options
are not global or shared).
However, until a loader has been updated to depend upon options being passed directly to them, the LoaderOptionsPlugin
exists to bridge the gap. You can configure global loader options with this plugin and all loaders will receive these options.
new webpack.LoaderOptionsPlugin({
// Options...
});
This plugin will be removed in the future as it only exists for migration.
This plugin supports the following options:
options.debug
(boolean
): Whether loaders should be in debug
mode or not. debug
will be removed as of webpack 3.options.minimize
(boolean
): Where loaders can be switched to minimize mode.options.options
(object
): A configuration object that can be used to configure older loaders - this will take the same schema a webpack.config.js
.options.options.context
(string
): The context that can be used to configure older loaders.webpack.config.js
....Here's an example of how this plugin might be used:
new webpack.LoaderOptionsPlugin({
minimize: true,
debug: false,
options: {
context: __dirname
}
});
Keep chunk size above the specified limit by merging chunks that are smaller than the minChunkSize
.
new webpack.optimize.MinChunkSizePlugin({
minChunkSize: 10000 // Minimum number of characters
});
This plugin and it's options can also be invoked via the CLI:
webpack --optimize-min-chunk-size 10000
This plugin extracts CSS into separate files. It creates a CSS file per JS file which contains CSS. It supports On-Demand-Loading of CSS and SourceMaps.
It builds on top of a new webpack v5 feature and requires webpack 5 to work.
Compared to the extract-text-webpack-plugin:
To begin, you'll need to install mini-css-extract-plugin
:
npm install --save-dev mini-css-extract-plugin
It's recommended to combine mini-css-extract-plugin
with the css-loader
Then add the loader and the plugin to your webpack
config. For example:
style.css
body {
background: green;
}
component.js
import "./style.css";
webpack.config.js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
plugins: [new MiniCssExtractPlugin()],
module: {
rules: [
{
test: /\.css$/i,
use: [MiniCssExtractPlugin.loader, "css-loader"],
},
],
},
};
⚠️ Note that if you import CSS from your webpack entrypoint or import styles in the initial chunk,
mini-css-extract-plugin
will not load this CSS into the page. Please usehtml-webpack-plugin
for automatic generationlink
tags or createindex.html
file withlink
tag.⚠️ Source maps works only for
source-map
/nosources-source-map
/hidden-nosources-source-map
/hidden-source-map
values because CSS only supports source maps with thesourceMappingURL
comment (i.e.//# sourceMappingURL=style.css.map
). If you need setdevtool
to another value you can enable source maps generation for extracted CSS usingsourceMap: true
forcss-loader
.
Name | Type | Default | Description |
---|---|---|---|
Name Type Default Description
|
{String\|Function} |
[name].css |
This option determines the name of each output CSS file |
Name Type Default Description
|
{String\|Function} |
based on filename |
This option determines the name of non-entry chunk files |
Name Type Default Description
|
{Boolean} |
false |
Remove Order Warnings |
Name Type Default Description
|
{String\|Function} |
document.head.appendChild(linkTag); |
Inserts the
link
tag at the given position for
non-initial (async)
CSS chunks |
Name Type Default Description
|
{Object} |
{} |
Adds custom attributes to the
link
tag for
non-initial (async)
CSS chunks |
Name Type Default Description
|
{String\|Boolean} |
text/css |
Allows loading asynchronous chunks with a custom link type |
Name Type Default Description
|
{Boolean} |
true |
Allows to enable/disable the runtime generation |
Name Type Default Description
|
{Boolean} |
undefined |
Use an experimental webpack API to execute modules instead of child compilers |
filename
Type: String|Function
Default: [name].css
This option determines the name of each output CSS file.
Works like output.filename
chunkFilename
Type: String|Function
Default: based on filename
i Specifying
chunkFilename
as afunction
is only available in webpack@5
This option determines the name of non-entry chunk files.
Works like output.chunkFilename
ignoreOrder
Type: Boolean
Default: false
Remove Order Warnings. See examples below for details.
insert
Type: String|Function
Default: document.head.appendChild(linkTag);
⚠️ Only for non-initial (async) chunks.
By default, the mini-css-extract-plugin
appends styles (<link>
elements) to document.head
of the current window
.
However in some circumstances it might be necessary to have finer control over the append target or even delay link
elements insertion.
For example this is the case when you asynchronously load styles for an application that runs inside of an iframe.
In such cases insert
can be configured to be a function or a custom selector.
If you target an iframe make sure that the parent document has sufficient access rights to reach into the frame document and append elements to it.
String
Allows to setup custom query selector.
A new <link>
element will be inserted after the found item.
webpack.config.js
new MiniCssExtractPlugin({
insert: "#some-element",
});
A new <link>
element will be inserted after the element with id some-element
.
Function
Allows to override default behavior and insert styles at any position.
⚠ Do not forget that this code will run in the browser alongside your application. Since not all browsers support latest ECMA features like
let
,const
,arrow function expression
and etc we recommend you to use only ECMA 5 features and syntax.⚠ The
insert
function is serialized to string and passed to the plugin. This means that it won't have access to the scope of the webpack configuration module.
webpack.config.js
new MiniCssExtractPlugin({
insert: function (linkTag) {
var reference = document.querySelector("#some-element");
if (reference) {
reference.parentNode.insertBefore(linkTag, reference);
}
},
});
A new <link>
element will be inserted before the element with id some-element
.
attributes
Type: Object
Default: {}
⚠️ Only for non-initial (async) chunks.
If defined, the mini-css-extract-plugin
will attach given attributes with their values on <link>
element.
webpack.config.js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
plugins: [
new MiniCssExtractPlugin({
attributes: {
id: "target",
"data-target": "example",
},
}),
],
module: {
rules: [
{
test: /\.css$/i,
use: [MiniCssExtractPlugin.loader, "css-loader"],
},
],
},
};
Note: It's only applied to dynamically loaded css chunks, if you want to modify link attributes inside html file, please using html-webpack-plugin
linkType
Type: String|Boolean
Default: text/css
This option allows loading asynchronous chunks with a custom link type, such as <link type="text/css" ...>
.
String
Possible values: text/css
webpack.config.js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
plugins: [
new MiniCssExtractPlugin({
linkType: "text/css",
}),
],
module: {
rules: [
{
test: /\.css$/i,
use: [MiniCssExtractPlugin.loader, "css-loader"],
},
],
},
};
Boolean
false
disables the link type
attribute
webpack.config.js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
plugins: [
new MiniCssExtractPlugin({
linkType: false,
}),
],
module: {
rules: [
{
test: /\.css$/i,
use: [MiniCssExtractPlugin.loader, "css-loader"],
},
],
},
};
runtime
Type: Boolean
Default: true
Allows to enable/disable the runtime generation. CSS will be still extracted and can be used for a custom loading methods. For example, you can use assets-webpack-plugin to retreive them then use your own runtime code to download assets when needed.
true
to skip.
webpack.config.js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
plugins: [
new MiniCssExtractPlugin({
runtime: false,
}),
],
module: {
rules: [
{
test: /\.css$/i,
use: [MiniCssExtractPlugin.loader, "css-loader"],
},
],
},
};
experimentalUseImportModule
Type: Boolean
Default: undefined
Enabled by default if not explicitly enabled (i.e. true
and false
allow you to explicitly control this option) and new API is available (at least webpack 5.52.0
is required).
Boolean values are available since version 5.33.2
, but you need to enable experiments.executeModule
(not required from webpack 5.52.0
).
Use a new webpack API to execute modules instead of child compilers. This improves performance and memory usage a lot.
When combined with experiments.layers
, this adds a layer
option to the loader options to specify the layer of the css execution.
webpack.config.js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
plugins: [
new MiniCssExtractPlugin({
// You don't need this for `>= 5.52.0` due to the fact that this is enabled by default
// Required only for `>= 5.33.2 & <= 5.52.0`
// Not avaliable/unsafe for `<= 5.33.2`
experimentalUseImportModule: true,
}),
],
module: {
rules: [
{
test: /\.css$/i,
use: [MiniCssExtractPlugin.loader, "css-loader"],
},
],
},
};
Name | Type | Default | Description |
---|---|---|---|
Name Type Default Description
|
{String\|Function} |
webpackOptions.output.publicPath |
Specifies a custom public path for the external resources like images, files, etc |
Name Type Default Description
|
{Boolean} |
true |
If false, the plugin will extract the CSS but will not emit the file |
Name Type Default Description
|
{Boolean} |
true |
Use ES modules syntax |
publicPath
Type: String|Function
Default: the publicPath
in webpackOptions.output
Specifies a custom public path for the external resources like images, files, etc inside CSS
.
Works like output.publicPath
String
webpack.config.js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
plugins: [
new MiniCssExtractPlugin({
// Options similar to the same options in webpackOptions.output
// both options are optional
filename: "[name].css",
chunkFilename: "[id].css",
}),
],
module: {
rules: [
{
test: /\.css$/,
use: [
{
loader: MiniCssExtractPlugin.loader,
options: {
publicPath: "/public/path/to/",
},
},
"css-loader",
],
},
],
},
};
Function
webpack.config.js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
plugins: [
new MiniCssExtractPlugin({
// Options similar to the same options in webpackOptions.output
// both options are optional
filename: "[name].css",
chunkFilename: "[id].css",
}),
],
module: {
rules: [
{
test: /\.css$/,
use: [
{
loader: MiniCssExtractPlugin.loader,
options: {
publicPath: (resourcePath, context) => {
return path.relative(path.dirname(resourcePath), context) + "/";
},
},
},
"css-loader",
],
},
],
},
};
emit
Type: Boolean
Default: true
If true, emits a file (writes a file to the filesystem). If false, the plugin will extract the CSS but will not emit the file. It is often useful to disable this option for server-side packages.
esModule
Type: Boolean
Default: true
By default, mini-css-extract-plugin
generates JS modules that use the ES modules syntax.
There are some cases in which using ES modules is beneficial, like in the case of module concatenation and tree shaking.
You can enable a CommonJS syntax using:
webpack.config.js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
plugins: [new MiniCssExtractPlugin()],
module: {
rules: [
{
test: /\.css$/i,
use: [
{
loader: MiniCssExtractPlugin.loader,
options: {
esModule: false,
},
},
"css-loader",
],
},
],
},
};
For production
builds it's recommended to extract the CSS from your bundle being able to use parallel loading of CSS/JS resources later on.
This can be achieved by using the mini-css-extract-plugin
, because it creates separate css files.
For development
mode (including webpack-dev-server
) you can use style-loader, because it injects CSS into the DOM using multiple and works faster.
i Do not use together
style-loader
andmini-css-extract-plugin
.
webpack.config.js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const devMode = process.env.NODE_ENV !== "production";
module.exports = {
module: {
rules: [
{
test: /\.(sa|sc|c)ss$/,
use: [
devMode ? "style-loader" : MiniCssExtractPlugin.loader,
"css-loader",
"postcss-loader",
"sass-loader",
],
},
],
},
plugins: [].concat(devMode ? [] : [new MiniCssExtractPlugin()]),
};
webpack.config.js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
plugins: [
new MiniCssExtractPlugin({
// Options similar to the same options in webpackOptions.output
// all options are optional
filename: "[name].css",
chunkFilename: "[id].css",
ignoreOrder: false, // Enable to remove warnings about conflicting order
}),
],
module: {
rules: [
{
test: /\.css$/,
use: [
{
loader: MiniCssExtractPlugin.loader,
options: {
// you can specify a publicPath here
// by default it uses publicPath in webpackOptions.output
publicPath: "../",
},
},
"css-loader",
],
},
],
},
};
⚠ Names of locals are converted to
camelCase
.⚠ It is not allowed to use JavaScript reserved words in css class names.
⚠ Options
esModule
andmodules.namedExport
incss-loader
should be enabled.
styles.css
.foo-baz {
color: red;
}
.bar {
color: blue;
}
index.js
import { fooBaz, bar } from "./styles.css";
console.log(fooBaz, bar);
You can enable a ES module named export using:
webpack.config.js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
plugins: [new MiniCssExtractPlugin()],
module: {
rules: [
{
test: /\.css$/,
use: [
{
loader: MiniCssExtractPlugin.loader,
},
{
loader: "css-loader",
options: {
esModule: true,
modules: {
namedExport: true,
localIdentName: "foo__[name]__[local]",
},
},
},
],
},
],
},
};
publicPath
option as functionwebpack.config.js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
plugins: [
new MiniCssExtractPlugin({
// Options similar to the same options in webpackOptions.output
// both options are optional
filename: "[name].css",
chunkFilename: "[id].css",
}),
],
module: {
rules: [
{
test: /\.css$/,
use: [
{
loader: MiniCssExtractPlugin.loader,
options: {
publicPath: (resourcePath, context) => {
// publicPath is the relative path of the resource to the context
// e.g. for ./css/admin/main.css the publicPath will be ../../
// while for ./css/main.css the publicPath will be ../
return path.relative(path.dirname(resourcePath), context) + "/";
},
},
},
"css-loader",
],
},
],
},
};
This plugin should not be used with style-loader
in the loaders chain.
Here is an example to have both HMR in development
and your styles extracted in a file for production
builds.
(Loaders options left out for clarity, adapt accordingly to your needs.)
You should not use HotModuleReplacementPlugin
plugin if you are using a webpack-dev-server
.
webpack-dev-server
enables / disables HMR using hot
option.
webpack.config.js
const webpack = require("webpack");
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const devMode = process.env.NODE_ENV !== "production";
const plugins = [
new MiniCssExtractPlugin({
// Options similar to the same options in webpackOptions.output
// both options are optional
filename: devMode ? "[name].css" : "[name].[contenthash].css",
chunkFilename: devMode ? "[id].css" : "[id].[contenthash].css",
}),
];
if (devMode) {
// only enable hot in development
plugins.push(new webpack.HotModuleReplacementPlugin());
}
module.exports = {
plugins,
module: {
rules: [
{
test: /\.(sa|sc|c)ss$/,
use: [
MiniCssExtractPlugin.loader,
"css-loader",
"postcss-loader",
"sass-loader",
],
},
],
},
};
Note: HMR is automatically supported in webpack 5. No need to configure it. Skip the following:
The mini-css-extract-plugin
supports hot reloading of actual css files in development.
Some options are provided to enable HMR of both standard stylesheets and locally scoped CSS or CSS modules.
Below is an example configuration of mini-css for HMR use with CSS modules.
You should not use HotModuleReplacementPlugin
plugin if you are using a webpack-dev-server
.
webpack-dev-server
enables / disables HMR using hot
option.
webpack.config.js
const webpack = require("webpack");
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const plugins = [
new MiniCssExtractPlugin({
// Options similar to the same options in webpackOptions.output
// both options are optional
filename: devMode ? "[name].css" : "[name].[contenthash].css",
chunkFilename: devMode ? "[id].css" : "[id].[contenthash].css",
}),
];
if (devMode) {
// only enable hot in development
plugins.push(new webpack.HotModuleReplacementPlugin());
}
module.exports = {
plugins,
module: {
rules: [
{
test: /\.css$/,
use: [
{
loader: MiniCssExtractPlugin.loader,
options: {},
},
"css-loader",
],
},
],
},
};
To minify the output, use a plugin like css-minimizer-webpack-plugin.
webpack.config.js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const CssMinimizerPlugin = require("css-minimizer-webpack-plugin");
module.exports = {
plugins: [
new MiniCssExtractPlugin({
filename: "[name].css",
chunkFilename: "[id].css",
}),
],
module: {
rules: [
{
test: /\.css$/,
use: [MiniCssExtractPlugin.loader, "css-loader"],
},
],
},
optimization: {
minimizer: [
// For webpack@5 you can use the `...` syntax to extend existing minimizers (i.e. `terser-webpack-plugin`), uncomment the next line
// `...`,
new CssMinimizerPlugin(),
],
},
};
This will enable CSS optimization only in production mode. If you want to run it also in development set the optimization.minimize
option to true.
The runtime code detects already added CSS via <link>
or <style>
tag.
This can be useful when injecting CSS on server-side for Server-Side-Rendering.
The href
of the <link>
tag has to match the URL that will be used for loading the CSS chunk.
The data-href
attribute can be used for <link>
and <style>
too.
When inlining CSS data-href
must be used.
The CSS can be extracted in one CSS file using optimization.splitChunks.cacheGroups
.
webpack.config.js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
optimization: {
splitChunks: {
cacheGroups: {
styles: {
name: "styles",
type: "css/mini-extract",
chunks: "all",
enforce: true,
},
},
},
},
plugins: [
new MiniCssExtractPlugin({
filename: "[name].css",
}),
],
module: {
rules: [
{
test: /\.css$/,
use: [MiniCssExtractPlugin.loader, "css-loader"],
},
],
},
};
Note that type
should be used instead of test
in Webpack 5, or else an extra .js
file can be generated besides the .css
file. This is because test
doesn't know which modules should be dropped (in this case, it won't detect that .js
should be dropped).
You may also extract the CSS based on the webpack entry name. This is especially useful if you import routes dynamically but want to keep your CSS bundled according to entry. This also prevents the CSS duplication issue one had with the ExtractTextPlugin.
const path = require("path");
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
entry: {
foo: path.resolve(__dirname, "src/foo"),
bar: path.resolve(__dirname, "src/bar"),
},
optimization: {
splitChunks: {
cacheGroups: {
fooStyles: {
type: "css/mini-extract",
name: "styles_foo",
chunks: (chunk) => {
return chunk.name === "foo";
},
enforce: true,
},
barStyles: {
type: "css/mini-extract",
name: "styles_bar",
chunks: (chunk) => {
return chunk.name === "bar";
},
enforce: true,
},
},
},
},
plugins: [
new MiniCssExtractPlugin({
filename: "[name].css",
}),
],
module: {
rules: [
{
test: /\.css$/,
use: [MiniCssExtractPlugin.loader, "css-loader"],
},
],
},
};
With the filename
option you can use chunk data to customize the filename.
This is particularly useful when dealing with multiple entry points and wanting to get more control out of the filename for a given entry point/chunk.
In the example below, we'll use filename
to output the generated css into a different directory.
webpack.config.js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
plugins: [
new MiniCssExtractPlugin({
filename: ({ chunk }) => `${chunk.name.replace("/js/", "/css/")}.css`,
}),
],
module: {
rules: [
{
test: /\.css$/,
use: [MiniCssExtractPlugin.loader, "css-loader"],
},
],
},
};
For long term caching use filename: "[contenthash].css"
. Optionally add [name]
.
webpack.config.js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
plugins: [
new MiniCssExtractPlugin({
filename: "[name].[contenthash].css",
chunkFilename: "[id].[contenthash].css",
}),
],
module: {
rules: [
{
test: /\.css$/,
use: [MiniCssExtractPlugin.loader, "css-loader"],
},
],
},
};
For projects where css ordering has been mitigated through consistent use of scoping or naming conventions, the css order warnings can be disabled by setting the ignoreOrder flag to true for the plugin.
webpack.config.js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
plugins: [
new MiniCssExtractPlugin({
ignoreOrder: true,
}),
],
module: {
rules: [
{
test: /\.css$/i,
use: [MiniCssExtractPlugin.loader, "css-loader"],
},
],
},
};
webpack.config.js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
entry: "./src/index.js",
module: {
rules: [
{
test: /\.s[ac]ss$/i,
oneOf: [
{
resourceQuery: "?dark",
use: [
Self.loader,
"css-loader",
{
loader: "sass-loader",
options: {
additionalData: `@use 'dark-theme/vars' as vars;`,
},
},
],
},
{
use: [
Self.loader,
"css-loader",
{
loader: "sass-loader",
options: {
additionalData: `@use 'light-theme/vars' as vars;`,
},
},
],
},
],
},
],
},
plugins: [
new Self({
filename: "[name].css",
attributes: {
id: "theme",
},
}),
],
};
src/index.js
import "./style.scss";
let theme = "light";
const themes = {};
themes[theme] = document.querySelector("#theme");
async function loadTheme(newTheme) {
// eslint-disable-next-line no-console
console.log(`CHANGE THEME - ${newTheme}`);
const themeElement = document.querySelector("#theme");
if (themeElement) {
themeElement.remove();
}
if (themes[newTheme]) {
// eslint-disable-next-line no-console
console.log(`THEME ALREADY LOADED - ${newTheme}`);
document.head.appendChild(themes[newTheme]);
return;
}
if (newTheme === "dark") {
// eslint-disable-next-line no-console
console.log(`LOADING THEME - ${newTheme}`);
import(/* webpackChunkName: "dark" */ "./style.scss?dark").then(() => {
themes[newTheme] = document.querySelector("#theme");
// eslint-disable-next-line no-console
console.log(`LOADED - ${newTheme}`);
});
}
}
document.onclick = () => {
if (theme === "light") {
theme = "dark";
} else {
theme = "light";
}
loadTheme(theme);
};
src/dark-theme/_vars.scss
$background: black;
src/light-theme/_vars.scss
$background: white;
src/styles.scss
body {
background-color: vars.$background;
}
public/index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Document</title>
<link id="theme" rel="stylesheet" type="text/css" href="./main.css" />
</head>
<body>
<script src="./main.js"></script>
</body>
</html>
If you'd like to extract the media queries from the extracted CSS (so mobile users don't need to load desktop or tablet specific CSS anymore) you should use one of the following plugins:
Please take a moment to read our contributing guidelines if you haven't yet done so.
In the past, one of webpack’s trade-offs when bundling was that each module in your bundle would be wrapped in individual function closures. These wrapper functions made it slower for your JavaScript to execute in the browser. In comparison, tools like Closure Compiler and RollupJS ‘hoist’ or concatenate the scope of all your modules into one closure and allow for your code to have a faster execution time in the browser.
This plugin will enable the same concatenation behavior in webpack. By default this plugin is already enabled in production mode
and disabled otherwise. If you need to override the production mode
optimization, set the optimization.concatenateModules
option to false
. To enable concatenation behavior in other modes, you can add ModuleConcatenationPlugin
manually or use the optimization.concatenateModules
option:
new webpack.optimize.ModuleConcatenationPlugin();
This concatenation behavior is called “scope hoisting.”
Scope hoisting is specifically a feature made possible by ECMAScript Module syntax. Because of this webpack may fallback to normal bundling based on what kind of modules you are using, and other conditions.
Keep in mind that this plugin will only be applied to ES6 modules processed directly by webpack. When using a transpiler, you'll need to disable module processing (e.g. the
modules
option in Babel).
As the article explains, webpack attempts to achieve partial scope hoisting. It will merge modules into a single scope but cannot do so in every case. If webpack cannot merge a module, the two alternatives are Prevent and Root. Prevent means the module must be in its own scope. Root means a new module group will be created. The following conditions determine the outcome:
Condition | Outcome |
---|---|
Condition Outcome Non ES6 Module Prevent |
Prevent |
Condition Outcome Imported By Non Import Root |
Root |
Condition Outcome Imported From Other Chunk Root |
Root |
Condition Outcome Imported By Multiple Other Module Groups Root |
Root |
Condition Outcome Imported With Root |
Root |
Condition Outcome Affected By Prevent |
Prevent |
Condition Outcome HMR Accepted Root |
Root |
Condition Outcome Using Prevent |
Prevent |
Condition Outcome In Multiple Chunks Prevent |
Prevent |
Condition Outcome
Prevent |
Prevent |
The following pseudo JavaScript explains the algorithm:
modules.forEach(module => {
const group = new ModuleGroup({
root: module
});
module.dependencies.forEach(dependency => {
tryToAdd(group, dependency);
});
if (group.modules.length > 1) {
orderedModules = topologicalSort(group.modules);
concatenatedModule = new ConcatenatedModule(orderedModules);
chunk.add(concatenatedModule);
orderedModules.forEach(groupModule => {
chunk.remove(groupModule);
});
}
});
function tryToAdd(group, module) {
if (group.has(module)) {
return true;
}
if (!hasPreconditions(module)) {
return false;
}
const nextGroup = group;
const result = module.dependents.reduce((check, dependent) => {
return check && tryToAdd(nextGroup, dependent);
}, true);
if (!result) {
return false;
}
module.dependencies.forEach(dependency => {
tryToAdd(group, dependency);
});
group.merge(nextGroup);
return true;
}
When using the webpack CLI, the --display-optimization-bailout
flag will display bailout reasons. When using the webpack config, just add the following to the stats
object:
module.exports = {
//...
stats: {
// Examine all modules
maxModules: Infinity,
// Display bailout reasons
optimizationBailout: true
}
};
webpack has a rich plugin interface. Most of the features within webpack itself use this plugin interface. This makes webpack flexible.
Name | Description |
---|---|
Name Description Minification with babel-minify |
Minification with babel-minify |
Name Description Add a banner to the top of each generated chunk |
Add a banner to the top of each generated chunk |
Name Description Extract common modules shared between chunks |
Extract common modules shared between chunks |
Name Description Prepare compressed versions of assets to serve them with Content-Encoding |
Prepare compressed versions of assets to serve them with Content-Encoding |
Name Description Override the inferred context of a |
Override the inferred context of a
require
expression |
Name Description Copies individual files or entire directories to the build directory |
Copies individual files or entire directories to the build directory |
Name Description Allow global constants configured at compile time |
Allow global constants configured at compile time |
Name Description Split bundles in order to drastically improve build time |
Split bundles in order to drastically improve build time |
Name Description Shorthand for using the |
Shorthand for using the
DefinePlugin
on
process.env
keys |
Name Description Extract text (CSS) from your bundles into a separate file |
Extract text (CSS) from your bundles into a separate file |
Name Description Enable Hot Module Replacement (HMR) |
Enable Hot Module Replacement (HMR) |
Name Description Easily create HTML files to serve your bundles |
Easily create HTML files to serve your bundles |
Name Description Add i18n support to your bundles |
Add i18n support to your bundles |
Name Description Exclude certain modules from bundles |
Exclude certain modules from bundles |
Name Description Set min/max limits for chunking to better control chunking |
Set min/max limits for chunking to better control chunking |
Name Description Used for migrating from webpack 1 to 2 |
Used for migrating from webpack 1 to 2 |
Name Description Keep chunk size above the specified limit |
Keep chunk size above the specified limit |
Name Description creates a CSS file per JS file which requires CSS |
creates a CSS file per JS file which requires CSS |
Name Description Skip the emitting phase when there are compilation errors |
Skip the emitting phase when there are compilation errors |
Name Description Replace resource(s) that matches a regexp |
Replace resource(s) that matches a regexp |
Name Description Auto-install missing dependencies during development |
Auto-install missing dependencies during development |
Name Description Report compilation progress |
Report compilation progress |
Name Description Use modules without having to use import/require |
Use modules without having to use import/require |
Name Description Enables a more fine grained control of source maps |
Enables a more fine grained control of source maps |
Name Description Enables a more fine grained control of eval source maps |
Enables a more fine grained control of eval source maps |
Name Description Enables control of the version of UglifyJS in your project |
Enables control of the version of UglifyJS in your project |
Name Description Enables control of the version of Terser in your project |
Enables control of the version of Terser in your project |
Name Description Prepare compressed versions of assets with node-zopfli |
Prepare compressed versions of assets with node-zopfli |
For more third-party plugins, see the list from awesome-webpack.
The NormalModuleReplacementPlugin
allows you to replace resources that match resourceRegExp
with newResource
. If newResource
is relative, it is resolved relative to the previous resource. If newResource
is a function, it is expected to overwrite the request attribute of the supplied resource.
This can be useful for allowing different behaviour between builds.
new webpack.NormalModuleReplacementPlugin(
resourceRegExp,
newResource
);
Replace a specific module when building for a development environment.
Say you have a config file some/path/config.development.module.js
and a special version for production in some/path/config.production.module.js
Just add the following plugin when building for production:
new webpack.NormalModuleReplacementPlugin(
/some\/path\/config\.development\.js/,
'./config.production.js'
);
Conditional build depending on an specified environment.
Say you want a configuration with specific values for different build targets.
module.exports = function(env) {
var appTarget = env.APP_TARGET || 'VERSION_A';
return {
plugins: [
new webpack.NormalModuleReplacementPlugin(/(.*)-APP_TARGET(\.*)/, function(resource) {
resource.request = resource.request.replace(/-APP_TARGET/, `-${appTarget}`);
})
]
};
};
Create the two config files:
app/config-VERSION_A.js
export default {
title : 'I am version A'
};
app/config-VERSION_B.js
export default {
title : 'I am version B'
};
Then import that config using the keyword you're looking for in the regexp:
import config from 'app/config-APP_TARGET';
console.log(config.title);
And now you just get the right config imported depending on which target you're building for:
webpack --env.APP_TARGET VERSION_A
=> 'I am version A'
webpack --env.APP_TARGET VERSION_B
=> 'I am version B'
Speed up development by automatically installing & saving dependencies with Webpack.
It is inefficient to Ctrl-C your build script & server just to install a dependency you didn't know you needed until now.
Instead, use require
or import
how you normally would and installation
will happen automatically to install & save missing dependencies while you work!
$ npm install --save-dev install-webpack-plugin
In your webpack.config.js
:
plugins: [
new InstallPlugin()
],
This is equivalent to:
plugins: [
new InstallPlugin({
dependencies: {
peer: true,
},
packageManager: {
type: this.getDefaultPackageManager(),
options: {
dev: false,
quiet: false,
},
},
prompt: true,
});
],
Type: Object
Dependencies related options.
Type: Boolean
Default: true
Install missing peer dependencies.
plugins: [
new InstallPlugin({
dependencies: {
peer: true,
}
}),
],
Type: 'npm' | 'yarn' | 'pnpm' | Object | Function
Package manager to use for installing dependencies.
plugins: [
new InstallPlugin({
packageManager: 'yarn'
},
}),
],
You can provide a Function
to the packageManager
to make it dynamic:
plugins: [
new InstallPlugin({
packageManager: function(module, path) {
return [
"babel-preset-react-hmre",
"webpack-dev-middleware",
"webpack-hot-middleware",
].indexOf(module) !== -1;
},
}),
],
Type: 'npm' | 'yarn' | 'pnpm'
Name of package manager to use for installing dependencies.
Type: Object
Package manager related options.
Type: Array
Provide custom arguments to use with package manager.
plugins: [
new InstallPlugin({
packageManager: {
type: 'npm',
options: {
arguments: ['--ignore-scripts']
}
}
},
}),
],
Type: Boolean
Default: false
Install as development dependencies.
plugins: [
new InstallPlugin({
packageManager: {
type: 'npm',
options: {
dev: true,
}
}
},
}),
],
Type: Boolean
Default: false
Reduce the amount of console logging.
plugins: [
new InstallPlugin({
packageManager: {
type: 'npm',
options: {
quiet: true,
}
}
},
}),
],
Type: Boolean
Default: true
Show a prompt to confirm installation.
plugins: [
new InstallPlugin({
prompt: true,
},
}),
],
^v5.0.0
..babelrc
plugins & presets.require
, import
)@cycle/dom
)lodash.capitalize
)@import "~bootstrap"
)babel-loader
, file-loader
, etc.)require("bundle?lazy!./App"
)peerDependencies
.
(e.g. @cycle/core
will automatically install rx@*
)resolve.alias
& resolve.root
configuration.
(e.g. require("react")
can alias to react-lite
)Please take a moment to read our contributing guidelines if you haven't yet done so.
Prefetch normal module requests, causing them to be resolved and built before the first import
or require
of that module occurs. Using this plugin can boost performance. Try to profile the build first to determine clever prefetching points.
new webpack.PrefetchPlugin([context], request);
context
: An absolute path to a directoryrequest
: A request string for a normal moduleGenerate Chrome profile file which includes timings of plugins execution. Outputs events.json
file by default. It is possible to provide custom file path using outputPath
option.
outputPath
: A relative path to a custom output file (json)new webpack.debug.ProfilingPlugin();
outputPath
new webpack.debug.ProfilingPlugin({
outputPath: 'profiling/profileEvents.json'
});
In order to view the profile file:
ProfilingPlugin
.Performance
tab (formerly Timeline
).events.json
by default) into the profiler.It will then display timeline stats and calls per plugin!
object = { boolean activeModules = true, boolean entries = false, function (number percentage, string message, [string] ...args) handler, boolean modules = true, number modulesCount = 500, boolean profile = false }
function (number percentage, string message, [string] ...args)
The ProgressPlugin
provides a way to customize how progress is reported during a compilation.
Create an instance of ProgressPlugin
and provide one of the allowed params.
function
Provide a handler function which will be called when hooks report progress. handler
function arguments:
percentage
: a number between 0 and 1 indicating the completion percentage of the compilationmessage
: a short description of the currently-executing hook...args
: zero or more additional strings describing the current progressconst handler = (percentage, message, ...args) => {
// e.g. Output each progress message directly to the console:
console.info(percentage, message, ...args);
};
new webpack.ProgressPlugin(handler);
object
When providing an object
to the ProgressPlugin
, following properties are supported:
activeModules
show's active modules count and one active module in progress messageentries
show's entries count in progress messagehandler: function (percentage, message, ...args)
modules
show's modules count in progress messagemodulesCount
a minimum modules count to start with. Takes effect when modules
property is enabled.profile
tells ProgressPlugin
to collect profile data for progress steps.new webpack.ProgressPlugin({
entries: true,
modules: true,
modulesCount: 100,
profile: true,
handler: (percentage, message, ...args) => {
// custom logic
}
});
The following hooks report progress information to ProgressPlugin
.
Hooks marked with * allow plugins to report progress information using
reportProgress
. For more, see Plugin API: Reporting Progress
Compiler
Compilation
Automatically load modules instead of having to import
or require
them everywhere.
new webpack.ProvidePlugin({
identifier: 'module1',
// ...
});
or
new webpack.ProvidePlugin({
identifier: ['module1', 'property1'],
// ...
});
By default, module resolution path is current folder (./**)
and node_modules
.
It is also possible to specify full path:
new webpack.ProvidePlugin({
identifier: path.resolve(path.join(__dirname, 'src/module1'))
// ...
});
Whenever the identifier
is encountered as free variable in a module, the module
is loaded automatically and the identifier
is filled with the exports of the loaded module
(or property
in order to support named exports).
For importing the default export of an ES2015 module, you have to specify the default property of module.
To automatically load jquery
we can simply point both variables it exposes to the corresponding node module:
new webpack.ProvidePlugin({
$: 'jquery',
jQuery: 'jquery'
});
Then in any of our source code:
// in a module
$('#item'); // <= just works
jQuery('#item'); // <= just works
// $ is automatically set to the exports of module "jquery"
Angular looks for window.jQuery
in order to determine whether jQuery is present, see the source code.
new webpack.ProvidePlugin({
'window.jQuery': 'jquery'
});
new webpack.ProvidePlugin({
_map: ['lodash', 'map']
});
new webpack.ProvidePlugin({
Vue: ['vue/dist/vue.esm.js', 'default']
});
This plugin enables more fine grained control of source map generation. It is also enabled automatically by certain settings of the devtool
configuration option.
new webpack.SourceMapDevToolPlugin(options);
The following options are supported:
test
(string
RegExp
[string, RegExp]
): Include source maps for modules based on their extension (defaults to .js
, .mjs
, and .css
).include
(string
RegExp
[string, RegExp]
): Include source maps for module paths that match the given value.exclude
(string
RegExp
[string, RegExp]
): Exclude modules that match the given value from source map generation.filename
(string
): Defines the output filename of the SourceMap (will be inlined if no value is provided).append
(string
): Appends the given value to the original asset. Usually the #sourceMappingURL
comment. [url]
is replaced with a URL to the source map file. Since webpack v4.36.0, path parameters are supported: [chunk]
, [filename]
and [contenthash]
. Setting append
to false
disables the appending.moduleFilenameTemplate
(string
): See output.devtoolModuleFilenameTemplate
.fallbackModuleFilenameTemplate
(string
): See link above.namespace
(string
): See output.devtoolNamespace
.module = true
(boolean
): Indicates whether loaders should generate source maps.columns = true
(boolean
): Indicates whether column mappings should be used.lineToLine
(boolean
object
): Simplify and speed up source mapping by using line to line source mappings for matched modules.noSources = false
(boolean
): Prevents the source file content from being included in the source map.publicPath
(string
): Emits absolute URLs with public path prefix, e.g. https://example.com/project/
.fileContext
(string
): Makes the [file]
argument relative to this directory.sourceRoot
(string
): Provide a custom value for the sourceRoot
property in the SourceMap.The lineToLine
object allows for the same test
, include
, and exclude
options described above.
The fileContext
option is useful when you want to store source maps in an upper level directory to avoid ../../
appearing in the absolute [url]
.
Setting
module
and/orcolumns
tofalse
will yield less accurate source maps but will also improve compilation performance significantly.
If you want to use a custom configuration for this plugin in development mode, make sure to disable the default one. I.e. set
devtool: false
.
Remember that when using the
TerserPlugin
, you must utilize thesourceMap
option.
The following examples demonstrate some common use cases for this plugin.
You can use the following code to replace the configuration option devtool: inline-source-map
with an equivalent custom plugin configuration:
module.exports = {
// ...
devtool: false,
plugins: [
new webpack.SourceMapDevToolPlugin({})
]
};
The following code would exclude source maps for any modules in the vendor.js
bundle:
new webpack.SourceMapDevToolPlugin({
filename: '[name].js.map',
exclude: ['vendor.js']
});
Set a URL for source maps. Useful for hosting them on a host that requires authorization.
new webpack.SourceMapDevToolPlugin({
append: '\n//# sourceMappingURL=https://example.com/sourcemap/[url]',
filename: '[name].map'
});
And for cases when source maps are stored in the upper level directory:
project
|- dist
|- public
|- bundle-[hash].js
|- sourcemaps
|- bundle-[hash].js.map
With next config:
new webpack.SourceMapDevToolPlugin({
filename: 'sourcemaps/[file].map',
publicPath: 'https://example.com/project/',
fileContext: 'public'
});
Will produce the following URL:
https://example.com/project/sourcemaps/bundle-[hash].js.map
Originally, chunks (and modules imported inside them) were connected by a parent-child relationship in the internal webpack graph. The CommonsChunkPlugin
was used to avoid duplicated dependencies across them, but further optimizations were not possible.
Since webpack v4, the CommonsChunkPlugin
was removed in favor of optimization.splitChunks
.
Out of the box SplitChunksPlugin
should work well for most users.
By default it only affects on-demand chunks, because changing initial chunks would affect the script tags the HTML file should include to run the project.
webpack will automatically split chunks based on these conditions:
node_modules
folderWhen trying to fulfill the last two conditions, bigger chunks are preferred.
webpack provides a set of options for developers that want more control over this functionality.
The default configuration was chosen to fit web performance best practices, but the optimal strategy for your project might differ. If you're changing the configuration, you should measure the impact of your changes to ensure there's a real benefit.
optimization.splitChunks
This configuration object represents the default behavior of the SplitChunksPlugin
.
webpack.config.js
module.exports = {
//...
optimization: {
splitChunks: {
chunks: 'async',
minSize: 30000,
maxSize: 0,
minChunks: 1,
maxAsyncRequests: 5,
maxInitialRequests: 3,
automaticNameDelimiter: '~',
automaticNameMaxLength: 30,
name: true,
cacheGroups: {
vendors: {
test: /[\\/]node_modules[\\/]/,
priority: -10
},
default: {
minChunks: 2,
priority: -20,
reuseExistingChunk: true
}
}
}
}
};
splitChunks.automaticNameDelimiter
string
By default webpack will generate names using origin and name of the chunk (e.g. vendors~main.js
). This option lets you specify the delimiter to use for the generated names.
splitChunks.automaticNameMaxLength
number = 109
Allows setting a maximum character count for chunk names that are generated by the SplitChunksPlugin
.
splitChunks.chunks
function (chunk)
string
This indicates which chunks will be selected for optimization. When a string is provided, valid values are all
, async
, and initial
. Providing all
can be particularly powerful, because it means that chunks can be shared even between async and non-async chunks.
webpack.config.js
module.exports = {
//...
optimization: {
splitChunks: {
// include all types of chunks
chunks: 'all'
}
}
};
Alternatively, you may provide a function for more control. The return value will indicate whether to include each chunk.
module.exports = {
//...
optimization: {
splitChunks: {
chunks (chunk) {
// exclude `my-excluded-chunk`
return chunk.name !== 'my-excluded-chunk';
}
}
}
};
You can combine this configuration with the HtmlWebpackPlugin. It will inject all the generated vendor chunks for you.
splitChunks.maxAsyncRequests
number
Maximum number of parallel requests when on-demand loading.
splitChunks.maxInitialRequests
number
Maximum number of parallel requests at an entry point.
splitChunks.minChunks
number
Minimum number of chunks that must share a module before splitting.
splitChunks.minSize
number
Minimum size, in bytes, for a chunk to be generated.
splitChunks.maxSize
number
Using maxSize
(either globally optimization.splitChunks.maxSize
per cache group optimization.splitChunks.cacheGroups[x].maxSize
or for the fallback cache group optimization.splitChunks.fallbackCacheGroup.maxSize
) tells webpack to try to split chunks bigger than maxSize
bytes into smaller parts. Parts will be at least minSize
(next to maxSize
) in size.
The algorithm is deterministic and changes to the modules will only have local impact. So that it is usable when using long term caching and doesn't require records. maxSize
is only a hint and could be violated when modules are bigger than maxSize
or splitting would violate minSize
.
When the chunk has a name already, each part will get a new name derived from that name. Depending on the value of optimization.splitChunks.hidePathInfo
it will add a key derived from the first module name or a hash of it.
maxSize
option is intended to be used with HTTP/2 and long term caching. It increases the request count for better caching. It could also be used to decrease the file size for faster rebuilding.
maxSize
takes higher priority thanmaxInitialRequest/maxAsyncRequests
. Actual priority ismaxInitialRequest/maxAsyncRequests < maxSize < minSize
.
splitChunks.name
boolean = true
function (module, chunks, cacheGroupKey) => string
string
Also available for each cacheGroup: splitChunks.cacheGroups.{cacheGroup}.name
.
The name of the split chunk. Providing true
will automatically generate a name based on chunks and cache group key.
Providing a string or a function allows you to use a custom name. Specifying either a string or a function that always returns the same string will merge all common modules and vendors into a single chunk. This might lead to bigger initial downloads and slow down page loads.
If you choose to specify a function, you may find the chunk.name
and chunk.hash
properties (where chunk
is an element of the chunks
array) particularly useful in choosing a name for your chunk.
If the splitChunks.name
matches an entry point name, the entry point will be removed.
It is recommended to set
splitChunks.name
tofalse
for production builds so that it doesn't change names unnecessarily.
main.js
import _ from 'lodash';
console.log(_.join(['Hello', 'webpack'], ' '));
webpack.config.js
module.exports = {
//...
optimization: {
splitChunks: {
cacheGroups: {
commons: {
test: /[\\/]node_modules[\\/]/,
// cacheGroupKey here is `commons` as the key of the cacheGroup
name(module, chunks, cacheGroupKey) {
const moduleFileName = module.identifier().split('/').reduceRight(item => item);
const allChunksNames = chunks.map((item) => item.name).join('~');
return `${cacheGroupKey}-${allChunksNames}-${moduleFileName}`;
},
chunks: 'all'
}
}
}
}
};
Running webpack with following splitChunks
configuration would also output a chunk of the group common with next name: commons-main-lodash.js.e7519d2bb8777058fa27.js
(hash given as an example of real world output).
When assigning equal names to different split chunks, all vendor modules are placed into a single shared chunk, though it's not recommend since it can result in more code downloaded.
splitChunks.cacheGroups
Cache groups can inherit and/or override any options from splitChunks.*
; but test
, priority
and reuseExistingChunk
can only be configured on cache group level. To disable any of the default cache groups, set them to false
.
webpack.config.js
module.exports = {
//...
optimization: {
splitChunks: {
cacheGroups: {
default: false
}
}
}
};
splitChunks.cacheGroups.{cacheGroup}.priority
number
A module can belong to multiple cache groups. The optimization will prefer the cache group with a higher priority
. The default groups have a negative priority to allow custom groups to take higher priority (default value is 0
for custom groups).
splitChunks.cacheGroups.{cacheGroup}.reuseExistingChunk
boolean
If the current chunk contains modules already split out from the main bundle, it will be reused instead of a new one being generated. This can impact the resulting file name of the chunk.
webpack.config.js
module.exports = {
//...
optimization: {
splitChunks: {
cacheGroups: {
vendors: {
reuseExistingChunk: true
}
}
}
}
};
splitChunks.cacheGroups.{cacheGroup}.test
function (module, chunk) => boolean
RegExp
string
Controls which modules are selected by this cache group. Omitting it selects all modules. It can match the absolute module resource path or chunk names. When a chunk name is matched, all modules in the chunk are selected.
webpack.config.js
module.exports = {
//...
optimization: {
splitChunks: {
cacheGroups: {
vendors: {
test(module, chunks) {
//...
return module.type === 'javascript/auto';
}
}
}
}
}
};
splitChunks.cacheGroups.{cacheGroup}.filename
string
Allows to override the filename when and only when it's an initial chunk.
All placeholders available in output.filename
are also available here.
This option can also be set globally in
splitChunks.filename
, but this isn't recommended and will likely lead to an error ifsplitChunks.chunks
is not set to'initial'
. Avoid setting it globally.
webpack.config.js
module.exports = {
//...
optimization: {
splitChunks: {
cacheGroups: {
vendors: {
filename: '[name].bundle.js'
}
}
}
}
};
splitChunks.cacheGroups.{cacheGroup}.enforce
boolean = false
Tells webpack to ignore splitChunks.minSize
, splitChunks.minChunks
, splitChunks.maxAsyncRequests
and splitChunks.maxInitialRequests
options and always create chunks for this cache group.
webpack.config.js
module.exports = {
//...
optimization: {
splitChunks: {
cacheGroups: {
vendors: {
enforce: true
}
}
}
}
};
// index.js
import('./a'); // dynamic import
// a.js
import 'react';
//...
Result: A separate chunk would be created containing react
. At the import call this chunk is loaded in parallel to the original chunk containing ./a
.
Why:
node_modules
react
is bigger than 30kbWhat's the reasoning behind this? react
probably won't change as often as your application code. By moving it into a separate chunk this chunk can be cached separately from your app code (assuming you are using chunkhash, records, Cache-Control or other long term cache approach).
// entry.js
// dynamic imports
import('./a');
import('./b');
// a.js
import './helpers'; // helpers is 40kb in size
//...
// b.js
import './helpers';
import './more-helpers'; // more-helpers is also 40kb in size
//...
Result: A separate chunk would be created containing ./helpers
and all dependencies of it. At the import calls this chunk is loaded in parallel to the original chunks.
Why:
helpers
is bigger than 30kbPutting the content of helpers
into each chunk will result into its code being downloaded twice. By using a separate chunk this will only happen once. We pay the cost of an additional request, which could be considered a tradeoff. That's why there is a minimum size of 30kb.
Create a commons
chunk, which includes all code shared between entry points.
webpack.config.js
module.exports = {
//...
optimization: {
splitChunks: {
cacheGroups: {
commons: {
name: 'commons',
chunks: 'initial',
minChunks: 2
}
}
}
}
};
This configuration can enlarge your initial bundles, it is recommended to use dynamic imports when a module is not immediately needed.
Create a vendors
chunk, which includes all code from node_modules
in the whole application.
webpack.config.js
module.exports = {
//...
optimization: {
splitChunks: {
cacheGroups: {
commons: {
test: /[\\/]node_modules[\\/]/,
name: 'vendors',
chunks: 'all'
}
}
}
}
};
This might result in a large chunk containing all external packages. It is recommended to only include your core frameworks and utilities and dynamically load the rest of the dependencies.
Create a custom vendor
chunk, which contains certain node_modules
packages matched by RegExp
.
webpack.config.js
module.exports = {
//...
optimization: {
splitChunks: {
cacheGroups: {
vendor: {
test: /[\\/]node_modules[\\/](react|react-dom)[\\/]/,
name: 'vendor',
chunks: 'all',
}
}
}
}
};
This will result in splitting
react
andreact-dom
into a separate chunk. If you're not sure what packages have been included in a chunk you may refer to Bundle Analysis section for details.
This plugin uses stylelint
that helps you avoid errors and enforce conventions in your styles.
To begin, you'll need to install stylelint-webpack-plugin
:
npm install stylelint-webpack-plugin --save-dev
Note: You also need to install stylelint >= 13
from npm, if you haven't already:
npm install stylelint --save-dev
Then add the plugin to your webpack config. For example:
const StylelintPlugin = require('stylelint-webpack-plugin');
module.exports = {
// ...
plugins: [new StylelintPlugin(options)],
// ...
};
See stylelint's options for the complete list of options available. These options are passed through to the stylelint
directly.
configFile
String
undefined
Specify the config file location to be used by stylelint
.
Note: By default this is handled by stylelint
.
context
String
compiler.context
A string indicating the root of your files.
exclude
String|Array[String]
['node_modules', compiler.options.output.path]
Specify the files and/or directories to exclude. Must be relative to options.context
.
extensions
String|Array[String]
['css', 'scss', 'sass']
Specify extensions that should be checked.
files
String|Array[String]
null
Specify directories, files, or globs. Must be relative to options.context
. Directories are traveresed recursively looking for files matching options.extensions
. File and glob patterns ignore options.extensions
.
fix
Boolean
false
If true
, stylelint
will fix as many errors as possible. The fixes are made to the actual source files. All unfixed errors will be reported. See Autofixing errors docs.
formatter
String|Function
'string'
Specify the formatter that you would like to use to format your results. See formatter option.
lintDirtyModulesOnly
Boolean
false
Lint only changed files, skip lint on start.
stylelintPath
String
stylelint
Path to stylelint
instance that will be used for linting.
threads
Boolean | Number
false
Set to true for an auto-selected pool size based on number of cpus. Set to a number greater than 1 to set an explicit pool size. Set to false, 1, or less to disable and only run in main process.
By default the plugin will auto adjust error reporting depending on stylelint errors/warnings counts.
You can still force this behavior by using emitError
or emitWarning
options:
emitError
Boolean
true
The errors found will always be emitted, to disable set to false
.
emitWarning
Boolean
true
The warnings found will always be emitted, to disable set to false
.
failOnError
Boolean
true
Will cause the module build to fail if there are any errors, to disable set to false
.
failOnWarning
Boolean
false
Will cause the module build to fail if there are any warnings, if set to true
.
quiet
Boolean
false
Will process and report errors only and ignore warnings, if set to true
.
outputReport
Boolean|Object
false
Write the output of the errors to a file, for example a json
file for use for reporting.
The filePath
is relative to the webpack config: output.path
.
You can pass in a different formatter for the output file, if none is passed in the default/configured formatter will be used.
{
filePath: 'path/to/file';
formatter: 'json';
}
This plugin uses terser to minify/minimize your JavaScript.
Webpack v5 comes with the latest terser-webpack-plugin
out of the box. If you are using Webpack v5 or above and wish to customize the options, you will still need to install terser-webpack-plugin
. Using Webpack v4, you have to install terser-webpack-plugin
v4.
To begin, you'll need to install terser-webpack-plugin
:
$ npm install terser-webpack-plugin --save-dev
Then add the plugin to your webpack
config. For example:
webpack.config.js
const TerserPlugin = require("terser-webpack-plugin");
module.exports = {
optimization: {
minimize: true,
minimizer: [new TerserPlugin()],
},
};
And run webpack
via your preferred method.
Works only with source-map
, inline-source-map
, hidden-source-map
and nosources-source-map
values for the devtool
option.
Why?
eval
wraps modules in eval("string")
and the minimizer does not handle strings.cheap
has not column information and minimizer generate only a single line, which leave only a single mapping.Using supported devtool
values enable source map generation.
Name | Type | Default | Description |
---|---|---|---|
Name Type Default Description
|
String\|RegExp\|Array<String\|RegExp> |
/\.m?js(\?.*)?$/i |
Test to match files against. |
Name Type Default Description
|
String\|RegExp\|Array<String\|RegExp> |
undefined |
Files to include. |
Name Type Default Description
|
String\|RegExp\|Array<String\|RegExp> |
undefined |
Files to exclude. |
Name Type Default Description
|
Boolean\|Number |
true |
Use multi-process parallel running to improve the build speed. |
Name Type Default Description
|
Function |
TerserPlugin.terserMinify |
Allows you to override default minify function. |
Name Type Default Description
|
Object |
default |
Terser minify options . |
Name Type Default Description
|
Boolean\|String\|RegExp\|Function<(node, comment) -> Boolean\|Object>\|Object |
true |
Whether comments shall be extracted to a separate file. |
test
Type: String|RegExp|Array<String|RegExp>
Default: /\.m?js(\?.*)?$/i
Test to match files against.
webpack.config.js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
test: /\.js(\?.*)?$/i,
}),
],
},
};
include
Type: String|RegExp|Array<String|RegExp>
Default: undefined
Files to include.
webpack.config.js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
include: /\/includes/,
}),
],
},
};
exclude
Type: String|RegExp|Array<String|RegExp>
Default: undefined
Files to exclude.
webpack.config.js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
exclude: /\/excludes/,
}),
],
},
};
parallel
Type: Boolean|Number
Default: true
Use multi-process parallel running to improve the build speed.
Default number of concurrent runs: os.cpus().length - 1
.
ℹ️ Parallelization can speedup your build significantly and is therefore highly recommended.
⚠️ If you use Circle CI or any other environment that doesn't provide real available count of CPUs then you need to setup explicitly number of CPUs to avoid
Error: Call retries were exceeded
(see #143, #202).
Boolean
Enable/disable multi-process parallel running.
webpack.config.js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
parallel: true,
}),
],
},
};
Number
Enable multi-process parallel running and set number of concurrent runs.
webpack.config.js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
parallel: 4,
}),
],
},
};
minify
Type: Function
Default: TerserPlugin.terserMinify
Allows you to override default minify function. By default plugin uses terser package. Useful for using and testing unpublished versions or forks.
⚠️ Always use
require
insideminify
function whenparallel
option enabled.
webpack.config.js
// Can be async
const minify = (input, sourceMap, minimizerOptions, extractsComments) => {
// The `minimizerOptions` option contains option from the `terserOptions` option
// You can use `minimizerOptions.myCustomOption`
// Custom logic for extract comments
const { map, code } = require("uglify-module") // Or require('./path/to/uglify-module')
.minify(input, {
/* Your options for minification */
});
return { map, code, warnings: [], errors: [], extractedComments: [] };
};
// Used to regenerate `fullhash`/`chunkhash` between different implementation
// Example: you fix a bug in custom minimizer/custom function, but unfortunately webpack doesn't know about it, so you will get the same fullhash/chunkhash
// to avoid this you can provide version of your custom minimizer
// You don't need if you use only `contenthash`
minify.getMinimizerVersion = () => {
let packageJson;
try {
// eslint-disable-next-line global-require, import/no-extraneous-dependencies
packageJson = require("uglify-module/package.json");
} catch (error) {
// Ignore
}
return packageJson && packageJson.version;
};
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
terserOptions: {
myCustomOption: true,
},
minify,
}),
],
},
};
terserOptions
Type: Object
Default: default
Terser options.
webpack.config.js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
terserOptions: {
ecma: undefined,
parse: {},
compress: {},
mangle: true, // Note `mangle.properties` is `false` by default.
module: false,
// Deprecated
output: null,
format: null,
toplevel: false,
nameCache: null,
ie8: false,
keep_classnames: undefined,
keep_fnames: false,
safari10: false,
},
}),
],
},
};
extractComments
Type: Boolean|String|RegExp|Function<(node, comment) -> Boolean|Object>|Object
Default: true
Whether comments shall be extracted to a separate file, (see details).
By default extract only comments using /^\**!|@preserve|@license|@cc_on/i
regexp condition and remove remaining comments.
If the original file is named foo.js
, then the comments will be stored to foo.js.LICENSE.txt
.
The terserOptions.format.comments
option specifies whether the comment will be preserved, i.e. it is possible to preserve some comments (e.g. annotations) while extracting others or even preserving comments that have been extracted.
Boolean
Enable/disable extracting comments.
webpack.config.js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
extractComments: true,
}),
],
},
};
String
Extract all
or some
(use /^\**!|@preserve|@license|@cc_on/i
RegExp) comments.
webpack.config.js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
extractComments: "all",
}),
],
},
};
RegExp
All comments that match the given expression will be extracted to the separate file.
webpack.config.js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
extractComments: /@extract/i,
}),
],
},
};
Function<(node, comment) -> Boolean>
All comments that match the given expression will be extracted to the separate file.
webpack.config.js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
extractComments: (astNode, comment) => {
if (/@extract/i.test(comment.value)) {
return true;
}
return false;
},
}),
],
},
};
Object
Allow to customize condition for extract comments, specify extracted file name and banner.
webpack.config.js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
extractComments: {
condition: /^\**!|@preserve|@license|@cc_on/i,
filename: (fileData) => {
// The "fileData" argument contains object with "filename", "basename", "query" and "hash"
return `${fileData.filename}.LICENSE.txt${fileData.query}`;
},
banner: (licenseFile) => {
return `License information can be found in ${licenseFile}`;
},
},
}),
],
},
};
condition
Type: Boolean|String|RegExp|Function<(node, comment) -> Boolean|Object>
Condition what comments you need extract.
webpack.config.js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
extractComments: {
condition: "some",
filename: (fileData) => {
// The "fileData" argument contains object with "filename", "basename", "query" and "hash"
return `${fileData.filename}.LICENSE.txt${fileData.query}`;
},
banner: (licenseFile) => {
return `License information can be found in ${licenseFile}`;
},
},
}),
],
},
};
filename
Type: String|Function<(string) -> String>
Default: [file].LICENSE.txt[query]
Available placeholders: [file]
, [query]
and [filebase]
([base]
for webpack 5).
The file where the extracted comments will be stored.
Default is to append the suffix .LICENSE.txt
to the original filename.
⚠️ We highly recommend using the
txt
extension. Usingjs
/cjs
/mjs
extensions may conflict with existing assets which leads to broken code.
webpack.config.js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
extractComments: {
condition: /^\**!|@preserve|@license|@cc_on/i,
filename: "extracted-comments.js",
banner: (licenseFile) => {
return `License information can be found in ${licenseFile}`;
},
},
}),
],
},
};
banner
Type: Boolean|String|Function<(string) -> String>
Default: /*! For license information please see ${commentsFile} */
The banner text that points to the extracted file and will be added on top of the original file.
Can be false
(no banner), a String
, or a Function<(string) -> String>
that will be called with the filename where extracted comments have been stored.
Will be wrapped into comment.
webpack.config.js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
extractComments: {
condition: true,
filename: (fileData) => {
// The "fileData" argument contains object with "filename", "basename", "query" and "hash"
return `${fileData.filename}.LICENSE.txt${fileData.query}`;
},
banner: (commentsFile) => {
return `My custom banner about license information ${commentsFile}`;
},
},
}),
],
},
};
Extract all legal comments (i.e. /^\**!|@preserve|@license|@cc_on/i
) and preserve /@license/i
comments.
webpack.config.js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
terserOptions: {
format: {
comments: /@license/i,
},
},
extractComments: true,
}),
],
},
};
If you avoid building with comments, use this config:
webpack.config.js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
terserOptions: {
format: {
comments: false,
},
},
extractComments: false,
}),
],
},
};
uglify-js
UglifyJS
is a JavaScript parser, minifier, compressor and beautifier toolkit.
webpack.config.js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
minify: TerserPlugin.uglifyJsMinify,
// `terserOptions` options will be passed to `uglify-js`
// Link to options - https://github.com/mishoo/UglifyJS#minify-options
terserOptions: {},
}),
],
},
};
swc
swc
is a super-fast compiler written in rust; producing widely-supported javascript from modern standards and typescript.
⚠ the
extractComments
option is not supported and all comments will be removed by default, it will be fixed in future
webpack.config.js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
minify: TerserPlugin.swcMinify,
// `terserOptions` options will be passed to `swc` (`@swc/core`)
// Link to options - https://swc.rs/docs/config-js-minify
terserOptions: {},
}),
],
},
};
esbuild
esbuild
is an extremely fast JavaScript bundler and minifier.
⚠ the
extractComments
option is not supported and all legal comments (i.e. copyright, licenses and etc) will be preserved
webpack.config.js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
minify: TerserPlugin.esbuildMinify,
// `terserOptions` options will be passed to `esbuild`
// Link to options - https://esbuild.github.io/api/#minify
// Note: the `minify` options is true by default (and override other `minify*` options), so if you want to disable the `minifyIdentifiers` option (or other `minify*` options) please use:
// terserOptions: {
// minify: false,
// minifyWhitespace: true,
// minifyIdentifiers: false,
// minifySyntax: true,
// },
terserOptions: {},
}),
],
},
};
Override default minify function - use uglify-js
for minification.
webpack.config.js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
minify: (file, sourceMap) => {
// https://github.com/mishoo/UglifyJS2#minify-options
const uglifyJsOptions = {
/* your `uglify-js` package options */
};
if (sourceMap) {
uglifyJsOptions.sourceMap = {
content: sourceMap,
};
}
return require("uglify-js").minify(file, uglifyJsOptions);
},
}),
],
},
};
With default terser minify function:
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
terserOptions: {
compress: true,
},
}),
],
},
};
With built-in minify functions:
import type { JsMinifyOptions as SwcOptions } from "@swc/core";
import type { MinifyOptions as UglifyJSOptions } from "uglify-js";
import type { TransformOptions as EsbuildOptions } from "esbuild";
import type { MinifyOptions as TerserOptions } from "terser";
module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin<SwcOptions>({
minify: TerserPlugin.swcMinify,
terserOptions: {
// `swc` options
},
}),
new TerserPlugin<UglifyJSOptions>({
minify: TerserPlugin.uglifyJsMinify,
terserOptions: {
// `uglif-js` options
},
}),
new TerserPlugin<EsbuildOptions>({
minify: TerserPlugin.esbuildMinify,
terserOptions: {
// `esbuild` options
},
}),
// Alternative usage:
new TerserPlugin<TerserOptions>({
minify: TerserPlugin.terserMinify,
terserOptions: {
// `terser` options
},
}),
],
},
};
Please take a moment to read our contributing guidelines if you haven't yet done so.
This plugin uses uglify-js to minify your JavaScript.
This module requires a minimum of Node v6.9.0 and Webpack v4.0.0.
To begin, you'll need to install uglifyjs-webpack-plugin
:
$ npm install uglifyjs-webpack-plugin --save-dev
Then add the plugin to your webpack
config. For example:
webpack.config.js
const UglifyJsPlugin = require('uglifyjs-webpack-plugin');
module.exports = {
optimization: {
minimizer: [new UglifyJsPlugin()],
},
};
And run webpack
via your preferred method.
test
Type: String|RegExp|Array<String|RegExp>
Default: /\.js(\?.*)?$/i
Test to match files against.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
test: /\.js(\?.*)?$/i,
}),
],
},
};
include
Type: String|RegExp|Array<String|RegExp>
Default: undefined
Files to include.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
include: /\/includes/,
}),
],
},
};
exclude
Type: String|RegExp|Array<String|RegExp>
Default: undefined
Files to exclude.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
exclude: /\/excludes/,
}),
],
},
};
chunkFilter
Type: Function<(chunk) -> boolean>
Default: () => true
Allowing to filter which chunks should be uglified (by default all chunks are uglified).
Return true
to uglify the chunk, false
otherwise.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
chunkFilter: (chunk) => {
// Exclude uglification for the `vendor` chunk
if (chunk.name === 'vendor') {
return false;
}
return true;
},
}),
],
},
};
cache
Type: Boolean|String
Default: false
Enable file caching.
Default path to cache directory: node_modules/.cache/uglifyjs-webpack-plugin
.
ℹ️ If you use your own
minify
function please read theminify
section for cache invalidation correctly.
Boolean
Enable/disable file caching.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
cache: true,
}),
],
},
};
String
Enable file caching and set path to cache directory.
webpack.config.js
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
cache: 'path/to/cache',
}),
],
},
};
cacheKeys
Type: Function<(defaultCacheKeys, file) -> Object>
Default: defaultCacheKeys => defaultCacheKeys
Allows you to override default cache keys.
Default cache keys:
({
'uglify-js': require('uglify-js/package.json').version, // uglify version
'uglifyjs-webpack-plugin': require('../package.json').version, // plugin version
'uglifyjs-webpack-plugin-options': this.options, // plugin options
path: compiler.outputPath ? `${compiler.outputPath}/${file}` : file, // asset path
hash: crypto
.createHash('md4')
.update(input)
.digest('hex'), // source file hash
});
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
cache: true,
cacheKeys: (defaultCacheKeys, file) => {
defaultCacheKeys.myCacheKey = 'myCacheKeyValue';
return defaultCacheKeys;
},
}),
],
},
};
parallel
Type: Boolean|Number
Default: false
Use multi-process parallel running to improve the build speed.
Default number of concurrent runs: os.cpus().length - 1
.
ℹ️ Parallelization can speedup your build significantly and is therefore highly recommended.
Boolean
Enable/disable multi-process parallel running.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
parallel: true,
}),
],
},
};
Number
Enable multi-process parallel running and set number of concurrent runs.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
parallel: 4,
}),
],
},
};
sourceMap
Type: Boolean
Default: false
Use source maps to map error message locations to modules (this slows down the compilation).
If you use your own minify
function please read the minify
section for handling source maps correctly.
⚠️
cheap-source-map
options don't work with this plugin.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
sourceMap: true,
}),
],
},
};
minify
Type: Function
Default: undefined
Allows you to override default minify function. By default plugin uses uglify-js package. Useful for using and testing unpublished versions or forks.
⚠️ Always use
require
insideminify
function whenparallel
option enabled.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
minify(file, sourceMap) {
const extractedComments = [];
// Custom logic for extract comments
const { error, map, code, warnings } = require('uglify-module') // Or require('./path/to/uglify-module')
.minify(file, {
/* Your options for minification */
});
return { error, map, code, warnings, extractedComments };
},
}),
],
},
};
uglifyOptions
Type: Object
Default: default
UglifyJS minify options.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
uglifyOptions: {
warnings: false,
parse: {},
compress: {},
mangle: true, // Note `mangle.properties` is `false` by default.
output: null,
toplevel: false,
nameCache: null,
ie8: false,
keep_fnames: false,
},
}),
],
},
};
extractComments
Type: Boolean|String|RegExp|Function<(node, comment) -> Boolean|Object>
Default: false
Whether comments shall be extracted to a separate file, (see details).
By default extract only comments using /^\**!|@preserve|@license|@cc_on/i
regexp condition and remove remaining comments.
If the original file is named foo.js
, then the comments will be stored to foo.js.LICENSE
.
The uglifyOptions.output.comments
option specifies whether the comment will be preserved, i.e. it is possible to preserve some comments (e.g. annotations) while extracting others or even preserving comments that have been extracted.
Boolean
Enable/disable extracting comments.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
extractComments: true,
}),
],
},
};
String
Extract all
or some
(use /^\**!|@preserve|@license|@cc_on/i
RegExp) comments.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
extractComments: 'all',
}),
],
},
};
RegExp
All comments that match the given expression will be extracted to the separate file.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
extractComments: /@extract/i,
}),
],
},
};
Function<(node, comment) -> Boolean>
All comments that match the given expression will be extracted to the separate file.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
extractComments: function(astNode, comment) {
if (/@extract/i.test(comment.value)) {
return true;
}
return false;
},
}),
],
},
};
Object
Allow to customize condition for extract comments, specify extracted file name and banner.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
extractComments: {
condition: /^\**!|@preserve|@license|@cc_on/i,
filename(file) {
return `${file}.LICENSE`;
},
banner(licenseFile) {
return `License information can be found in ${licenseFile}`;
},
},
}),
],
},
};
condition
Type: Boolean|String|RegExp|Function<(node, comment) -> Boolean|Object>
Condition what comments you need extract.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
extractComments: {
condition: 'some',
filename(file) {
return `${file}.LICENSE`;
},
banner(licenseFile) {
return `License information can be found in ${licenseFile}`;
},
},
}),
],
},
};
filename
Type: Regex|Function<(string) -> String>
Default: ${file}.LICENSE
The file where the extracted comments will be stored.
Default is to append the suffix .LICENSE
to the original filename.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
extractComments: {
condition: /^\**!|@preserve|@license|@cc_on/i,
filename: 'extracted-comments.js',
banner(licenseFile) {
return `License information can be found in ${licenseFile}`;
},
},
}),
],
},
};
banner
Type: Boolean|String|Function<(string) -> String>
Default: /*! For license information please see ${commentsFile} */
The banner text that points to the extracted file and will be added on top of the original file.
Can be false
(no banner), a String
, or a Function<(string) -> String>
that will be called with the filename where extracted comments have been stored.
Will be wrapped into comment.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
extractComments: {
condition: true,
filename(file) {
return `${file}.LICENSE`;
},
banner(commentsFile) {
return `My custom banner about license information ${commentsFile}`;
},
},
}),
],
},
};
warningsFilter
Type: Function<(warning, source) -> Boolean>
Default: () => true
Allow to filter uglify-js warnings.
Return true
to keep the warning, false
otherwise.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
warningsFilter: (warning, source) => {
if (/Dropping unreachable code/i.test(warning)) {
return true;
}
if (/filename\.js/i.test(source)) {
return true;
}
return false;
},
}),
],
},
};
Enable cache and multi-process parallel running.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
cache: true,
parallel: true,
}),
],
},
};
Extract all legal comments (i.e. /^\**!|@preserve|@license|@cc_on/i
) and preserve /@license/i
comments.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
uglifyOptions: {
output: {
comments: /@license/i,
},
},
extractComments: true,
}),
],
},
};
If you avoid building with comments, set uglifyOptions.output.comments to false as in this config:
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
uglifyOptions: {
output: {
comments: false,
},
},
}),
],
},
};
Override default minify function - use terser for minification.
webpack.config.js
module.exports = {
optimization: {
minimizer: [
new UglifyJsPlugin({
// Uncomment lines below for cache invalidation correctly
// cache: true,
// cacheKeys(defaultCacheKeys) {
// delete defaultCacheKeys['uglify-js'];
//
// return Object.assign(
// {},
// defaultCacheKeys,
// { 'uglify-js': require('uglify-js/package.json').version },
// );
// },
minify(file, sourceMap) {
// https://github.com/mishoo/UglifyJS2#minify-options
const uglifyJsOptions = {
/* your `uglify-js` package options */
};
if (sourceMap) {
uglifyJsOptions.sourceMap = {
content: sourceMap,
};
}
return require('terser').minify(file, uglifyJsOptions);
},
}),
],
},
};
Please take a moment to read our contributing guidelines if you haven't yet done so.
Ignore the specified files, i.e. those matching the provided paths or regular expressions, while in watch mode.
new webpack.WatchIgnorePlugin(paths);
paths
([string, RegExp]
): A list of RegExps or absolute paths to directories or files that should be ignoredNode-Zopfli plugin for Webpack.
npm i -D zopfli-webpack-plugin
var ZopfliPlugin = require("zopfli-webpack-plugin");
module.exports = {
plugins: [
new ZopfliPlugin({
asset: "[path].gz[query]",
algorithm: "zopfli",
test: /\.(js|html)$/,
threshold: 10240,
minRatio: 0.8
})
]
}
asset
: The target asset name. [file]
is replaced with the original asset. [path]
is replaced with the path of the original asset and [query]
with the query. Defaults to "[path].gz[query]"
.filename
: A function(asset)
which receives the asset name (after processing asset
option) and returns the new asset name. Defaults to false
.algorithm
: Can be a function(buf, callback)
or a string. For a string the algorithm is taken from zopfli
.test
: All assets matching this RegExp are processed. Defaults to every asset.threshold
: Only assets bigger than this size are processed. In bytes. Defaults to 0
.minRatio
: Only assets that compress better that this ratio are processed. Defaults to 0.8
.deleteOriginalAssets
: Whether to delete the original assets or not. Defaults to false
.Juho Vepsäläinen | Joshua Wiens | Kees Kluskens | Sean Larkin |