[![npm][npm]][npm-url]
[![node][node]][node-url]
[![tests][tests]][tests-url]
[![cover][cover]][cover-url]
[![discussion][discussion]][discussion-url]
[![size][size]][size-url]
# minimizer-webpack-plugin
This plugin minifies your assets in a webpack build. It ships with several
built-in minimizers covering JavaScript, JSON, HTML, CSS, and images — pick one
with the [`minify`](#minify) option and target the right files with
[`test`](#test).
JavaScript minimizers:
- [`terser`](https://github.com/terser/terser) — `MinimizerPlugin.terserMinify` (default). The same JavaScript-based minifier that webpack uses out of the box; produces small, well-tested output and supports the full set of `extractComments` modes.
- [`uglify-js`](https://github.com/mishoo/UglifyJS) — `MinimizerPlugin.uglifyJsMinify`. ES5-only minifier, useful when you specifically need UglifyJS-compatible output. Requires `npm install --save-dev uglify-js`.
- [`@swc/core`](https://github.com/swc-project/swc) — `MinimizerPlugin.swcMinify`. A very fast Rust-based JavaScript/TypeScript minifier. Requires `npm install --save-dev @swc/core`.
- [`esbuild`](https://github.com/evanw/esbuild) — `MinimizerPlugin.esbuildMinify`. An extremely fast JS bundler/minifier; legal comments are always preserved (no `extractComments` support). Requires `npm install --save-dev esbuild`.
JSON minimizer:
- `JSON.stringify` — `MinimizerPlugin.jsonMinify`. Built in (no extra dependency); supports `space` and `replacer` options.
HTML minimizers:
- [`html-minifier-terser`](https://github.com/terser/html-minifier-terser) — `MinimizerPlugin.htmlMinifierTerser`. The default HTML minimizer. JavaScript-based, no native dependency. Requires `npm install --save-dev html-minifier-terser`.
- [`@swc/html`](https://github.com/swc-project/swc) — `MinimizerPlugin.swcMinifyHtml` (full HTML documents) and `MinimizerPlugin.swcMinifyHtmlFragment` (HTML fragments, e.g. `` content). Very fast Rust-based platform for the Web. Requires `npm install --save-dev @swc/html`.
- [`@minify-html/node`](https://github.com/wilsonzlin/minify-html) — `MinimizerPlugin.minifyHtmlNode`. A Rust HTML minifier optimised for speed and effectiveness. Requires `npm install --save-dev @minify-html/node`.
CSS minimizers:
- [`cssnano`](https://cssnano.github.io/cssnano/) — `MinimizerPlugin.cssnanoMinify`. The default CSS minimizer. Built on top of [PostCSS](https://postcss.org/). Requires `npm install --save-dev cssnano postcss`.
- [`csso`](https://github.com/css/csso) — `MinimizerPlugin.cssoMinify`. A CSS minifier with structural optimisations. Requires `npm install --save-dev csso`.
- [`clean-css`](https://github.com/clean-css/clean-css) — `MinimizerPlugin.cleanCssMinify`. A widely-used CSS optimiser. Requires `npm install --save-dev clean-css`.
- [`esbuild`](https://github.com/evanw/esbuild) — `MinimizerPlugin.esbuildMinifyCss`. Very fast CSS minification using esbuild's CSS loader. Requires `npm install --save-dev esbuild`.
- [`lightningcss`](https://github.com/parcel-bundler/lightningcss) — `MinimizerPlugin.lightningCssMinify`. A Rust-based CSS parser, transformer, and minifier. Requires `npm install --save-dev lightningcss`.
- [`@swc/css`](https://github.com/swc-project/swc) — `MinimizerPlugin.swcMinifyCss`. A very fast Rust-based CSS minifier. Requires `npm install --save-dev @swc/css`.
Image minimizers:
- [`sharp`](https://github.com/lovell/sharp) — `MinimizerPlugin.sharpMinify`. Re-encodes an image as the format its name already claims (`avif`, `gif`, `heif`, `jp2`, `jpeg`, `png`, `tiff`, `webp`), and can resize, rotate, flip, grayscale, blur or sharpen on the way — from the options or from the asset's own name. Requires `npm install --save-dev sharp`.
- [`svgo`](https://github.com/svg/svgo) — `MinimizerPlugin.svgoMinify`. Minifies SVG, including an `asset/inline` SVG that no `test` can match. Requires `npm install --save-dev svgo`.
- [`imagemin`](https://github.com/imagemin/imagemin) — `MinimizerPlugin.imageminMinify`. Runs the `imagemin` plugins you name. Requires `npm install --save-dev imagemin` plus each plugin.
- [`@napi-rs/image`](https://github.com/Brooooooklyn/Image) — `MinimizerPlugin.napiRsImageMinify`. Rust codecs with no system dependency; recompresses `png` losslessly with oxipng and `jpeg` with mozjpeg, and can resize, turn, mirror, grayscale, invert or blur on the way — from the options or from the asset's own name. Requires `npm install --save-dev @napi-rs/image`.
These only minify — they never change an image's format or name; see
[Images](#images).
All of the non-default minimizers are declared as **optional** peer
dependencies — install only the ones you actually use. You can also stack
multiple `MinimizerPlugin` instances in the same build to handle different
file types with different minimizers (see [Examples](#examples)).
## Getting Started
Webpack v5 comes with the latest `minimizer-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 `minimizer-webpack-plugin`.
Using Webpack v4, you have to install `terser-webpack-plugin` v4 (`minimizer-webpack-plugin` is only published for Webpack v5+).
To begin, you'll need to install `minimizer-webpack-plugin`:
```console
npm install minimizer-webpack-plugin --save-dev
```
or
```console
yarn add -D minimizer-webpack-plugin
```
or
```console
pnpm add -D minimizer-webpack-plugin
```
Then add the plugin to your `webpack` configuration. For example:
**webpack.config.js**
```js
const MinimizerPlugin = require("minimizer-webpack-plugin");
module.exports = {
optimization: {
minimize: true,
minimizer: [new MinimizerPlugin()],
},
};
```
Finally, run `webpack` using the method you normally use (e.g., via CLI or an npm script).
## Note about source maps
**Works only with `source-map`, `inline-source-map`, `hidden-source-map` and `nosources-source-map` values for the [`devtool`](https://webpack.js.org/configuration/devtool/) option.**
Why?
- `eval` wraps modules in `eval("string")` and the minimizer does not handle strings.
- `cheap` has no column information and the minimizer generates only a single line, which leaves only a single mapping.
Using supported `devtool` values enable source map generation.
## Options
- **[`test`](#test)**
- **[`include`](#include)**
- **[`exclude`](#exclude)**
- **[`parallel`](#parallel)**
- **[`minify`](#minify)**
- **[`minimizerOptions`](#minimizeroptions)**
- **[`extractComments`](#extractcomments)**
### `test`
Type:
```ts
type test = string | RegExp | (string | RegExp)[];
```
Default: `/\.m?js(\?.*)?$/i`
Test to match files against.
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new MinimizerPlugin({
test: /\.js(\?.*)?$/i,
}),
],
},
};
```
### `include`
Type:
```ts
type include = string | RegExp | (string | RegExp)[];
```
Default: `undefined`
Files to include.
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new MinimizerPlugin({
include: /\/includes/,
}),
],
},
};
```
### `exclude`
Type:
```ts
type exclude = string | RegExp | (string | RegExp)[];
```
Default: `undefined`
Files to exclude.
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new MinimizerPlugin({
exclude: /\/excludes/,
}),
],
},
};
```
### `parallel`
Type:
```ts
type parallel = boolean | number;
```
Default: `true`
Use multi-process parallel running to improve the build speed.
Default number of concurrent runs: `os.cpus().length - 1` or `os.availableParallelism() - 1` (if this function is supported).
> **Note**
>
> Parallelization can speedup your build significantly and is therefore **highly recommended**.
> **Warning**
>
> If you use **Circle CI** or any other environment that doesn't provide the real available count of CPUs then you need to explicitly set up the number of CPUs to avoid `Error: Call retries were exceeded` (see [#143](https://github.com/webpack/minimizer-webpack-plugin/issues/143), [#202](https://github.com/webpack/minimizer-webpack-plugin/issues/202)).
#### `boolean`
Enable/disable multi-process parallel running.
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new MinimizerPlugin({
parallel: true,
}),
],
},
};
```
#### `number`
Enable multi-process parallel running and set number of concurrent runs.
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new MinimizerPlugin({
parallel: 4,
}),
],
},
};
```
### `minify`
Type:
```ts
type minifyFn = (
input: Record,
sourceMap: import("@jridgewell/trace-mapping").SourceMapInput | undefined,
minifyOptions: {
module?: boolean | undefined;
ecma?: import("terser").ECMA | undefined;
},
extractComments:
| boolean
| "all"
| "some"
| RegExp
| ((
astNode: any,
comment: {
value: string;
type: "comment1" | "comment2" | "comment3" | "comment4";
pos: number;
line: number;
col: number;
},
) => boolean)
| {
condition?:
| boolean
| "all"
| "some"
| RegExp
| ((
astNode: any,
comment: {
value: string;
type: "comment1" | "comment2" | "comment3" | "comment4";
pos: number;
line: number;
col: number;
},
) => boolean)
| undefined;
filename?: string | ((fileData: any) => string) | undefined;
banner?:
string | boolean | ((commentsFile: string) => string) | undefined;
}
| undefined,
) => Promise<{
code: string;
map?: import("@jridgewell/trace-mapping").SourceMapInput | undefined;
errors?: (string | Error)[] | undefined;
warnings?: (string | Error)[] | undefined;
extractedComments?: string[] | undefined;
}>;
type minify = minifyFn | minifyFn[];
```
Default: `MinimizerPlugin.terserMinify`
Allows you to override the default minify function.
By default plugin uses [terser](https://github.com/terser/terser) package.
Useful for using and testing unpublished versions or forks.
An array of functions can also be provided. Each minimizer can expose a
`filter(name, info)` helper that decides whether it should run on a given
asset; the plugin dispatches each asset only to the minimizers whose `filter`
accepts it (or runs them all when no filter is set). All built-in minimizers
ship with a `filter` that matches their natural extension, so a single plugin
instance and a single worker pool can handle JS, CSS, HTML and JSON together
without juggling multiple `MinimizerPlugin` instances — just widen `test` to
let those asset types reach the dispatcher:
```js
new MinimizerPlugin({
test: /\.(?:[cm]?js|css|html?|json)(\?.*)?$/i,
minify: [
MinimizerPlugin.terserMinify,
MinimizerPlugin.cssnanoMinify,
MinimizerPlugin.htmlMinifierTerser,
MinimizerPlugin.jsonMinify,
],
});
```
When more than one minimizer in the array claims the same asset, the chain
semantic still applies: the output of each accepting minimizer is fed as
input to the next. The [`minimizerOptions`](#minimizeroptions) option may
be an array (index-paired with `minify`) or a single object reused by every
minimizer.
The `test` option always defaults to `/\.[cm]?js(\?.*)?$/i`. When you mix
asset types in a single plugin instance, widen `test` so non-JS assets reach
the dispatcher (for example `test: /\.(?:[cm]?js|css|html?|json)(\?.*)?$/i`).
> **Warning**
>
> **Always use `require` inside `minify` function when `parallel` option enabled**.
#### `function`
**webpack.config.js**
```js
// Can be async
const minify = (input, sourceMap, minimizerOptions, extractsComments) => {
// The `minimizerOptions` argument contains options from the `minimizerOptions` plugin 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 {
packageJson = require("uglify-module/package.json");
} catch (error) {
// Ignore
}
return packageJson && packageJson.version;
};
// Restrict the minimizer to the assets it can actually handle. The plugin
// skips assets for which `filter` returns `false` and (when an array of
// minimizers is used) dispatches each asset only to the minimizers that
// accept it. Returning `undefined` is treated as accept.
minify.filter = (name) => /\.[cm]?js(\?.*)?$/i.test(name);
// Declare this when the minimizer reads the asset's bytes rather than its
// text — an image minimizer. Its `input` values then arrive as a `Buffer` and
// its `code` may be one. Only applied when every minimizer an asset is
// dispatched to declares it, since one that does not could not read the bytes.
minify.supportsBinary = () => true;
module.exports = {
optimization: {
minimize: true,
minimizer: [
new MinimizerPlugin({
minimizerOptions: {
myCustomOption: true,
},
minify,
}),
],
},
};
```
#### `array`
If an array of functions is passed to the `minify` option, each asset is
dispatched to the minimizers whose `filter` accepts it. When more than one
minimizer accepts the same asset the output of each is fed as input to the
next one (the chain semantic). The `minimizerOptions` option can be either an
array of option objects (index-paired with `minify`) or a single object that
will be shared by all minimizers. Warnings, errors and extracted comments
from all running minimizers are merged together.
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new MinimizerPlugin({
minify: [MinimizerPlugin.terserMinify, MinimizerPlugin.swcMinify],
// `minimizerOptions` can be an array of options, one per `minify` entry
minimizerOptions: [
// Options for `MinimizerPlugin.terserMinify`
{ mangle: false },
// Options for `MinimizerPlugin.swcMinify`
{},
],
}),
],
},
};
```
A single plugin instance can also handle multiple asset types — the built-in
minimizers each ship with a `filter` matching their natural extension, so JS,
CSS, HTML and JSON can all be minified by one shared worker pool:
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new MinimizerPlugin({
// `test` still defaults to JS only, so widen it to catch every
// asset type you want the dispatcher to consider.
test: /\.(?:[cm]?js|css|html?|json)(\?.*)?$/i,
minify: [
MinimizerPlugin.terserMinify,
MinimizerPlugin.cssnanoMinify,
MinimizerPlugin.htmlMinifierTerser,
MinimizerPlugin.jsonMinify,
],
}),
],
},
};
```
### `minimizerOptions`
Type:
```ts
interface minimizerOptions {
compress?: boolean | CompressOptions;
ecma?: ECMA;
enclose?: boolean | string;
ie8?: boolean;
keep_classnames?: boolean | RegExp;
keep_fnames?: boolean | RegExp;
mangle?: boolean | MangleOptions;
module?: boolean;
nameCache?: object;
format?: FormatOptions;
/** @deprecated */
output?: FormatOptions;
parse?: ParseOptions;
safari10?: boolean;
sourceMap?: boolean | SourceMapOptions;
toplevel?: boolean;
}
type options = minimizerOptions | minimizerOptions[];
```
Default: [default](https://github.com/terser/terser#minify-options)
Options for the active minimizer. With the default Terser minify, see Terser's
[minify options](https://github.com/terser/terser#minify-options).
When the [`minify`](#minify) option is an array of minimizers, `minimizerOptions`
can also be an array. Each element is passed to the minimizer at the same
index in the `minify` array. If a single object is provided instead, it is
reused for every minimizer.
> **Note**
>
> `terserOptions` is kept as a deprecated alias of `minimizerOptions` for
> backwards compatibility — passing either is equivalent. If both are set,
> `minimizerOptions` wins. Prefer `minimizerOptions` in new code.
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new MinimizerPlugin({
minimizerOptions: {
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:
```ts
type extractComments =
| boolean
| string
| RegExp
| ((
astNode: any,
comment: {
value: string;
type: "comment1" | "comment2" | "comment3" | "comment4";
pos: number;
line: number;
col: number;
},
) => boolean)
| {
condition?:
| boolean
| "all"
| "some"
| RegExp
| ((
astNode: any,
comment: {
value: string;
type: "comment1" | "comment2" | "comment3" | "comment4";
pos: number;
line: number;
col: number;
},
) => boolean)
| undefined;
filename?: string | ((fileData: any) => string) | undefined;
banner?:
string | boolean | ((commentsFile: string) => string) | undefined;
};
```
Default: `true`
Whether comments shall be extracted to a separate file, (see [details](https://github.com/webpack/webpack/commit/71933e979e51c533b432658d5e37917f9e71595a)).
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 `minimizerOptions.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 preserve comments that have already been extracted.
#### `boolean`
Enable/disable extracting comments.
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new MinimizerPlugin({
extractComments: true,
}),
],
},
};
```
#### `string`
Extract `all` or `some` (use the `/^\**!|@preserve|@license|@cc_on/i` RegExp) comments.
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new MinimizerPlugin({
extractComments: "all",
}),
],
},
};
```
#### `RegExp`
All comments that match the given expression will be extracted to a separate file.
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new MinimizerPlugin({
extractComments: /@extract/i,
}),
],
},
};
```
#### `function`
All comments that match the given expression will be extracted to a separate file.
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new MinimizerPlugin({
extractComments: (astNode, comment) => {
if (/@extract/i.test(comment.value)) {
return true;
}
return false;
},
}),
],
},
};
```
#### `object`
Allows you to customize condition for extracting comments, and specify the extracted file name and banner.
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new MinimizerPlugin({
extractComments: {
condition: /^\**!|@preserve|@license|@cc_on/i,
filename: (fileData) =>
// The "fileData" argument contains object with "filename", "basename", "query" and "hash"
`${fileData.filename}.LICENSE.txt${fileData.query}`,
banner: (licenseFile) =>
`License information can be found in ${licenseFile}`,
},
}),
],
},
};
```
##### `condition`
Type:
```ts
type condition =
| boolean
| "all"
| "some"
| RegExp
| ((
astNode: any,
comment: {
value: string;
type: "comment1" | "comment2" | "comment3" | "comment4";
pos: number;
line: number;
col: number;
},
) => boolean)
| undefined;
```
The condition that determines which comments should be extracted.
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new MinimizerPlugin({
extractComments: {
condition: "some",
filename: (fileData) =>
// The "fileData" argument contains object with "filename", "basename", "query" and "hash"
`${fileData.filename}.LICENSE.txt${fileData.query}`,
banner: (licenseFile) =>
`License information can be found in ${licenseFile}`,
},
}),
],
},
};
```
##### `filename`
Type:
```ts
type filename = string | ((fileData: any) => string) | undefined;
```
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.
> **Warning**
>
> We highly recommend using the `.txt` extension. Using `.js`/`.cjs`/`.mjs` extensions may conflict with existing assets, which leads to broken code.
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new MinimizerPlugin({
extractComments: {
condition: /^\**!|@preserve|@license|@cc_on/i,
filename: "extracted-comments.js",
banner: (licenseFile) =>
`License information can be found in ${licenseFile}`,
},
}),
],
},
};
```
##### `banner`
Type:
```ts
type banner = string | boolean | ((commentsFile: string) => string) | undefined;
```
Default: `/*! For license information please see ${commentsFile} */`
The banner text that points to the extracted file and will be added at the top of the original file.
It can be `false` (no banner), a `String`, or a `function<(string) -> String>` that will be called with the filename where the extracted comments have been stored.
The banner will be wrapped in a comment.
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new MinimizerPlugin({
extractComments: {
condition: true,
filename: (fileData) =>
// The "fileData" argument contains object with "filename", "basename", "query" and "hash"
`${fileData.filename}.LICENSE.txt${fileData.query}`,
banner: (commentsFile) =>
`My custom banner about license information ${commentsFile}`,
},
}),
],
},
};
```
## Embedded source
Source written in one language that reaches the bundle inside another is
minified too, which no asset carries and an asset-level minimizer therefore
never sees. It needs no option (webpack `>= 5.110.0`; older versions reach only
what an asset nests inside itself).
Such source has no filename, so `test` / `include` / `exclude` and each
minimizer's `filter` — all of which match filenames — cannot dispatch it.
**It is dispatched by the language it is written in**, which every minify
function states for itself:
```js
myCssMinifier.getTypes = () => ["css"];
```
The built-ins declare `javascript` (`terserMinify`, `uglifyJsMinify`,
`swcMinify`, `esbuildMinify`), `css` (`cssnanoMinify`, `cssoMinify`,
`cleanCssMinify`, `esbuildMinifyCss`, `lightningCssMinify`, `swcMinifyCss`),
`html` (`htmlMinifierTerser`, `swcMinifyHtml`, `swcMinifyHtmlFragment`,
`minifyHtmlNode`) and `json` (`jsonMinify`); webpack's own `cssMinify` and
`htmlMinify` declare `css` and `html`. A language **no configured minimizer
claims — `svg` out of the box — is emitted exactly as it was written**, and a
custom minify function without `getTypes` is never handed embedded source at
all.
What this reaches:
- CSS and HTML a module embeds in a JavaScript string literal (every
`exportType` but `link`).
- The text an `asset/source` module embeds, and the payload an `asset/inline`
module encodes — the payload before it is encoded, so the encoding covers
what came back.
- What a document or a stylesheet nests inside itself: an inline `