README

# terser-webpack-plugin

This plugin uses terser to minify your JavaScript.

## Getting Started

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.

## Options

### <tt>test</tt>

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,
}),
],
},
};

### <tt>include</tt>

Type: `String|RegExp|Array<String|RegExp>` Default: `undefined`

Files to include.

webpack.config.js

module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
include: /\/includes/,
}),
],
},
};

### <tt>exclude</tt>

Type: `String|RegExp|Array<String|RegExp>` Default: `undefined`

Files to exclude.

webpack.config.js

module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
exclude: /\/excludes/,
}),
],
},
};

### <tt>cache</tt>

> ⚠ Ignored in webpack 5! Please use https://webpack.js.org/configuration/other-options/#cache.

Type: `Boolean|String` Default: `true`

Enable file caching. Default path to cache directory: `node_modules/.cache/terser-webpack-plugin`.

> ℹ️ If you use your own `minify` function please read the `minify` section for cache invalidation correctly.

#### <tt>Boolean</tt>

Enable/disable file caching.

webpack.config.js

module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
cache: true,
}),
],
},
};

#### <tt>String</tt>

Enable file caching and set path to cache directory.

webpack.config.js

module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
cache: 'path/to/cache',
}),
],
},
};

### <tt>cacheKeys</tt>

> ⚠ Ignored in webpack 5! Please use https://webpack.js.org/configuration/other-options/#cache.

Type: `Function<(defaultCacheKeys, file) -> Object>` Default: `defaultCacheKeys => defaultCacheKeys`

Allows you to override default cache keys.

Default cache keys:

({
terser: require('terser/package.json').version, // terser version
'terser-webpack-plugin': require('../package.json').version, // plugin version
'terser-webpack-plugin-options': this.options, // plugin options
nodeVersion: process.version, // Node.js version
name: file, // asset path
contentHash: crypto.createHash('md4').update(input).digest('hex'), // source file hash
});

webpack.config.js

module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
cache: true,
cacheKeys: (defaultCacheKeys, file) => {
defaultCacheKeys.myCacheKey = 'myCacheKeyValue';
return defaultCacheKeys;
},
}),
],
},
};

### <tt>parallel</tt>

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).

#### <tt>Boolean</tt>

Enable/disable multi-process parallel running.

webpack.config.js

module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
parallel: true,
}),
],
},
};

#### <tt>Number</tt>

Enable multi-process parallel running and set number of concurrent runs.

webpack.config.js

module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
parallel: 4,
}),
],
},
};

### <tt>sourceMap</tt>

Type: `Boolean` Default: `false` (see below for details around `devtool` value and `SourceMapDevToolPlugin` plugin)

**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.

The plugin respect the `devtool` and using the `SourceMapDevToolPlugin` plugin. Using supported `devtool` values enable source map generation. Using `SourceMapDevToolPlugin` with enabled the `columns` option enables source map generation.

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.

webpack.config.js

module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
sourceMap: true,
}),
],
},
};

### <tt>minify</tt>

Type: `Function` Default: `undefined`

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` inside `minify` function when `parallel` option enabled.

webpack.config.js

module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
// Can be async
minify: (file, sourceMap) => {
const extractedComments = [];
// Custom logic for extract comments
const { map, code } = require('uglify-module') // Or require('./path/to/uglify-module')
.minify(file, {
/* Your options for minification */
});
return { map, code, extractedComments };
},
}),
],
},
};

### <tt>terserOptions</tt>

Type: `Object` Default: default

Terser minify 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,
output: null,
toplevel: false,
nameCache: null,
ie8: false,
keep_classnames: undefined,
keep_fnames: false,
safari10: false,
},
}),
],
},
};

### <tt>extractComments</tt>

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.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.

#### <tt>Boolean</tt>

Enable/disable extracting comments.

webpack.config.js

module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
extractComments: true,
}),
],
},
};

#### <tt>String</tt>

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',
}),
],
},
};

#### <tt>RegExp</tt>

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,
}),
],
},
};

#### <tt>Function<(node, comment) -> Boolean></tt>

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;
},
}),
],
},
};

#### <tt>Object</tt>

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. Using `js`/`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}`;
},
},
}),
],
},
};

## Examples

### Preserve Comments

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: {
output: {
comments: /@license/i,
},
},
extractComments: true,
}),
],
},
};

### Remove Comments

If you avoid building with comments, use this config:

webpack.config.js

module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
terserOptions: {
output: {
comments: false,
},
},
extractComments: false,
}),
],
},
};

### Custom Minify Function

Override default minify function - use `uglify-js` for minification.

webpack.config.js

module.exports = {
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
// Uncomment lines below for cache invalidation correctly
// cache: true,
// cacheKeys: (defaultCacheKeys) => {
// delete defaultCacheKeys.terser;
//
// 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('uglify-js').minify(file, uglifyJsOptions);
},
}),
],
},
};

## Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

./.github/CONTRIBUTING.md "CONTRIBUTING"

## License

MIT