terser-webpack-plugin

What is terser-webpack-plugin?

The terser-webpack-plugin is a plugin for webpack that uses Terser to minify JavaScript files. It can improve the performance of web applications by reducing the size of the JavaScript bundle, which decreases loading times for users. It also offers options for code compression, mangling, and potentially other optimizations that can be configured to suit various deployment needs.

What are terser-webpack-plugin's main functionalities?

Minification

This feature allows you to minify your JavaScript files, removing unnecessary whitespace, comments, and code. It helps in reducing the file size and improving load times for your web application.

const TerserPlugin = require('terser-webpack-plugin');

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

Source Map Support

This feature enables the generation of source maps, which help in debugging minified JavaScript by mapping the minified code back to the original source code.

const TerserPlugin = require('terser-webpack-plugin');

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

Code Compression

This feature allows for further compression of the JavaScript code, such as removing console logs and other statements that are not needed in production code.

const TerserPlugin = require('terser-webpack-plugin');

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

Mangling

Mangling reduces the size of your code by shortening the names of variables and functions to single characters. This feature is particularly useful for reducing the size of large codebases.

const TerserPlugin = require('terser-webpack-plugin');

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [new TerserPlugin({
      terserOptions: {
        mangle: true, // Note: `mangle` is `true` by default.
      },
    })],
  },
};

Other packages similar to terser-webpack-plugin

uglifyjs-webpack-plugin

This package is similar to terser-webpack-plugin as it also minifies JavaScript files. However, it uses UglifyJS for minification instead of Terser. Terser is a fork of UglifyJS with ES6+ support, so terser-webpack-plugin might be more suitable for projects using modern JavaScript features.

babel-minify-webpack-plugin

This plugin uses babel-minify for minifying JavaScript. It is similar to terser-webpack-plugin but leverages the Babel toolchain. It might be a better choice for projects that are already using Babel for JavaScript transpilation.

closure-webpack-plugin

Closure-webpack-plugin uses Google's Closure Compiler for minifying JavaScript, which is known for its advanced optimizations. It can be more aggressive in optimization compared to terser-webpack-plugin, but it may also require more configuration and might not support all modern JavaScript features as well as Terser.

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

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

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: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        chunkFilter: (chunk) => {
          // Exclude uglification for the `vendor` chunk
          if (chunk.name === 'vendor') {
            return false;
          }

          return true;
        },
      }),
    ],
  },
};

cache

⚠ Doesn't work with webpack 5!

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.

Boolean

Enable/disable file caching.

webpack.config.js

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

String

Enable file caching and set path to cache directory.

webpack.config.js

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

cacheKeys

⚠ Doesn't work with webpack 5!

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
  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: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        cache: true,
        cacheKeys: (defaultCacheKeys, file) => {
          defaultCacheKeys.myCacheKey = 'myCacheKeyValue';

          return defaultCacheKeys;
        },
      }),
    ],
  },
};

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.

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

sourceMap

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

minify

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

terserOptions

Type: Object Default: default

Terser minify options.

webpack.config.js

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        terserOptions: {
          ecma: undefined,
          warnings: false,
          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,
        },
      }),
    ],
  },
};

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

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: (file, fileData) => {
            // ⚠ webpack 5: there is only fileData parameter

            // A file can contain a query string (for example when you have `output.filename: '[name].js?[chunkhash]'`)
            // You must consider this
            // The "fileData" argument contains object with "filename", "basename", "query"
            return file.replace(/\.(\w+)($|\?)/, '.$1.LICENSE$2');
          },
          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: (file, fileData) => {
            // ⚠ webpack 5: there is only fileData parameter

            // A file can contain a query string (for example when you have `output.filename: '[name].js?[chunkhash]'`)
            // You must consider this
            return file.replace(/\.(\w+)($|\?)/, '.$1.LICENSE$2');
          },
          banner: (licenseFile) => {
            return `License information can be found in ${licenseFile}`;
          },
        },
      }),
    ],
  },
};

filename

Type: String|Function<(string) -> String> Default: [file].LICENSE[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 to the original filename.

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: (file, fileData) => {
            // ⚠ webpack 5: there is only fileData parameter

            // A file can contain a query string (for example when you have `output.filename: '[name].js?[chunkhash]'`)
            // You must consider this
            return file.replace(/\.(\w+)($|\?)/, '.$1.LICENSE$2');
          },
          banner: (commentsFile) => {
            return `My custom banner about license information ${commentsFile}`;
          },
        },
      }),
    ],
  },
};

warningsFilter

Type: Function<(warning, source, file) -> Boolean> Default: () => true

Allow to filter terser warnings. Return true to keep the warning, a falsy value (false/null/undefined) otherwise.

⚠️ The source argument will contain undefined if you don't use source maps.

webpack.config.js

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        warningsFilter: (warning, source, file) => {
          if (/Dropping unreachable code/i.test(warning)) {
            return true;
          }

          if (/source\.js/i.test(source)) {
            return true;
          }

          if (/file\.js/i.test(file)) {
            return true;
          }

          return false;
        },
      }),
    ],
  },
};

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.

CONTRIBUTING

License

MIT

Changelog

2.3.2 (2020-01-09)

Bug Fixes

• show error message from jest-worker (#203) (3b28007)