terser-webpack-plugin

5.5.0 verified Sat Apr 25 auth: no javascript

Webpack plugin that uses Terser to minify/minimize JavaScript output. Current stable version 5.5.0, with frequent releases (multiple per year). Ships TypeScript definitions. Key differentiator: integrates deeply with webpack's optimization pipeline, supports source maps, parallelization via worker threads, and custom minimizers (e.g., swc, esbuild). Requires webpack ^5.1.0. Active maintenance by webpack team.

Common errors

error Error: Call retries were exceeded (with parallel: true on Circle CI) ↓

cause Circle CI reports fewer CPUs than available, causing worker thread overload.

fix

Set parallel: false or parallel: 2 in plugin options.

error TypeError: Cannot read properties of undefined (reading 'source') ↓

cause TerserPlugin fails on empty JavaScript files when source maps are enabled.

fix

Update to v5.3.16+ or filter out empty files.

error Module not found: Error: Can't resolve 'terser-webpack-plugin' in ... ↓

cause Plugin not installed or installed as devDependency but used in non-dev context.

fix

Run 'npm install terser-webpack-plugin --save-dev'

error TypeScript error: 'TerserPlugin' cannot be used as a value because it is a type. ↓

cause Using import type incorrectly; TerserPlugin is a class, not a type.

fix

Use 'const TerserPlugin = require('terser-webpack-plugin')' or ESM default import.

error Warning: TerserWebpackPlugin: options.extractComments is deprecated. ↓

cause Default behavior for extractComments changed; explicit option required.

fix

Set extractComments: false or extractComments: true in plugin options.

Warnings

gotcha Using 'eval' devtool prevents source map generation; use 'source-map' instead. ↓

fix Set devtool to 'source-map', 'inline-source-map', 'hidden-source-map', or 'nosources-source-map'.

gotcha Parallelism defaults to os.cpus().length - 1; fails on Circle CI due to CPU limit. ↓

fix Set parallel to explicit number (e.g., 2) or false in CI environments.

breaking Webpack v5 includes terser-webpack-plugin out of the box; manual install only needed for customization. ↓

fix For webpack v5, install terser-webpack-plugin only if you want to override default options.

deprecated Since v5.3.11, extraction of comments by default may change; set extractComments explicitly. ↓

fix Set extractComments: false or extractComments: true in options to avoid deprecation warnings.

gotcha Empty files in source map processing cause errors prior to v5.3.16. ↓

fix Upgrade to v5.3.16 or higher.

breaking v1.x only supports webpack v4; v5.x only supports webpack v5. ↓

fix Use v4.x of this plugin for webpack v4, or v5.x for webpack v5.

gotcha Custom minimizer like swcMinify requires 'experimental' flag before v5.5.0. ↓

fix For swcMinify support, use v5.5.0+ and set minify: TerserPlugin.swcMinify.

Install

npm install terser-webpack-plugin

yarn add terser-webpack-plugin

pnpm add terser-webpack-plugin

Imports

TerserPlugin

wrong

import TerserPlugin from 'terser-webpack-plugin';

correct

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

CommonJS import is standard; ESM named export exists but is unconventional.

TerserPlugin (ESM)

wrong

import { TerserPlugin } from 'terser-webpack-plugin';

correct

import TerserPlugin from 'terser-webpack-plugin';

Default export only. No named export for TerserPlugin.

TerserPluginOptions (TypeScript)

import type { TerserPluginOptions } from 'terser-webpack-plugin';

Type import for options type.

Quickstart

Basic webpack configuration with TerserPlugin for JS minification, dropping console statements and comments.

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

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