AutomaticPrefetchPlugin

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.

webpack.config.js

export default {
  // ...
  plugins: [new webpack.AutomaticPrefetchPlugin()],
};

BannerPlugin

Adds a banner to the top of each generated chunk.

import webpack from "webpack";

new webpack.BannerPlugin(banner);
// or
new webpack.BannerPlugin(options);

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 | [string, RegExp], // Include all modules that pass test assertion.
  include: string | RegExp | [string, RegExp], // Include all modules matching any of these conditions.
  exclude: string | RegExp | [string, RegExp], // Exclude all modules matching any of these conditions.
  footer?: boolean, // if true, the banner will be placed at the end of the compilation
  stage?: number, // the stage of the compilation in which the banner should be injected
}

Usage

import webpack from "webpack";

// string
new webpack.BannerPlugin({
  banner: "hello world",
});

// function
new webpack.BannerPlugin({
  banner: (yourVariable) => `yourVariable: ${yourVariable}`,
});

// It will add the banner message after minimizers and any asset manipulation
new webpack.BannerPlugin({
  raw: true,
  banner: "/* banner is a string */",
  stage: webpack.Compilation.PROCESS_ASSETS_STAGE_REPORT,
});

Placeholders

Since webpack 2.5.0, placeholders are evaluated in the banner string:

import webpack from "webpack";

new webpack.BannerPlugin({
  banner:
    "fullhash:[fullhash], chunkhash:[chunkhash], name:[name], base:[base], query:[query], file:[file]",
});

ChunksWebpackPlugin

The chunks-webpack-plugin creates HTML files with entry points and chunks relations to serve your webpack bundles. It is suitable with multi-page applications that contain multiple entry points.

Since webpack 4, SplitChunksPlugin offers the possibility to optimizes all chunks. It can be particularly powerful, because it means that chunks can be shared even between async and non-async chunks. See the webpack documentation of splitChunks.chunks for details.

splitChunks.chunks option can be set to automatically generate new chunks associated with an entry point. For example, entry points a.js and b.js share common code with the file vendors~a~b.js.

With multiple entry points, it can be difficult to identify relation between the auto-generated chunks and entry points.

chunks-webpack-plugin parses the webpack compilation entry points to get all files associated with the entry points. Then, it generates HTML files which include all assets filtered by an entry point and thechunks-manifest.json file.

Zero configuration

It works without configuration. For advanced usage, see the using configuration section.

Installation

chunks-webpack-plugin is available on npm as chunks-webpack-plugin and as chunks-webpack-plugin on GitHub.

npm install chunks-webpack-plugin --save-dev

yarn add chunks-webpack-plugin --dev

[!WARNING] Plugin chunks-webpack-plugin@10 is ESM only. [!NOTE] Minimum supported Node.js version is 16.20.0 and Webpack >=5.10.3.

Example

The project includes a minimalist example in the ./example directory. Run the npm run build:example command to execute the Webpack example and see the plugin's implementation in action.

Basic usage

chunks-webpack-plugin will generate two HTML files for each entry point. Each filename contains the entry point name, the {{entry}} placeholder is automatically replaced.

• {{entry}}-styles.html: contains all HTML <link> tags
• {{entry}}-scripts.html: contains all HTML <script> tags

First, let's add the plugin to the webpack configuration.

webpack.config.js

import ChunksWebpackPlugin from 'chunks-webpack-plugin';

export default {
  plugins: [new ChunksWebpackPlugin()]
};

HTML files are built in the output path directory with the rest of the webpack compilation.

Now you can include the generated HTML files into your HTML page templates. You can do it with e.g. Twig.

main-styles.html

<link rel="stylesheet" href="main.css" />

main-scripts.html

<script defer src="main.js"></script>

Using a configuration

You can pass a configuration object to chunks-webpack-plugin to override the default settings.

filename

Type:

type filename = string;

Default: '[name]-[type].html'

Tells the plugin whether to personalize the filename of the generated files. Files are processed by the webpack compilation and generated in the output path directory. The placeholder [name] is automatically replaced by entry points names and [type] by styles|scripts.

new ChunksWebpackPlugin({
  filename: 'templates/[name]-[type].html'
});

[!NOTE] The filename can contain directories, which will be created automatically.

templateStyle

Type:

type templateStyle = (name: string, entryName: string) => string;

Default:

(name) => `<link rel="stylesheet" href="${name}" />`;

Tells the plugin whether to personalize the default template for the HTML <style> tags. For example, add additional attributes or a CDN prefix.

export default {
  plugins: [
    new ChunksWebpackPlugin({
      templateStyle: (name) => `<link rel="stylesheet" href="https://cdn.domain.com${name}" />`
    })
  ]
};

templateScript

Type:

type templateScript = (name: string, entryName: string) => string;

Default:

(name) => `<script defer src="${name}"></script>`;

Tells the plugin whether to personalize the default template for the HTML <script> tags. For example, add additional attributes or a CDN prefix.

export default {
  plugins: [
    new ChunksWebpackPlugin({
      templateScript: (name) => `<script defer src="https://cdn.domain.com${name}"></script>`
    })
  ]
};

generateChunksManifest

Type:

type generateChunksManifest = boolean;

Default: false

Tells the plugin whether to generate the chunks-manifest.json. The file contains the list of all chunks grouped by entry points. See the chunks-manifest.json example.

export default {
  plugins: [
    new ChunksWebpackPlugin({
      generateChunksManifest: true
    })
  ]
};

generateChunksFiles

Type:

type generateChunksFiles = boolean;

Default: true

Tells the plugin whether to generate the HTML files.

export default {
  plugins: [
    new ChunksWebpackPlugin({
      generateChunksFiles: false
    })
  ]
};

[!WARNING] When set to false, HTML files will not be generated. It can only be useful together with generateChunksManifest option set to true for custom generation of the HTML files.

import ChunksWebpackPlugin from 'chunks-webpack-plugin';
import path from 'node:path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

export default {
  entry: {
    home: 'home.js',
    news: 'news.js'
  },
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, './dist')
  },
  plugins: [new ChunksWebpackPlugin()],
  optimization: {
    splitChunks: {
      chunks: 'all'
    }
  }
};

<link rel="stylesheet" href="vendors~home~news.css" />
<link rel="stylesheet" href="home.css" />

<script defer src="vendors~home~news.js"></script>
<script defer src="home.js"></script>

<link rel="stylesheet" href="vendors~home~news.css" />
<link rel="stylesheet" href="news.css" />

<script defer src="vendors~home~news.js"></script>
<script defer src="news.js"></script>

License

chunks-webpack-plugin is licensed under the MIT License.

Created with ♥ by @yoriiis.

ContextExclusionPlugin

Context refers to dynamic expressions in import() or require() such as require('./locale/' + name + '.json').

The ContextExclusionPlugin allows you to exclude context. Provide RegExp as an argument when initializing the Plugin to exclude all context that matches it.

webpack.config.js

export default {
  plugins: [new webpack.ContextExclusionPlugin(/dont/)],
};

ContextReplacementPlugin

Context refers to dynamic expressions in import() or require() 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:

Usage

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

Content Callback

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

Other Options

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

CopyPlugin

Copies files and directories into output.path as part of the build. This is the plugin behind output.copy, and webpack applies it for you when that option is set — reach for the plugin directly when you need one of the two options output.copy does not carry, concurrency and stage.

import webpack from "webpack";

new webpack.CopyPlugin(options);

Options

{
  patterns: (string | object)[], // what is copied, see output.copy
  concurrency?: number, // how many files are read at the same time
  stage?: number, // the processAssets stage the files are copied at
}

• patterns ((string | object)[]): the files to copy. A pattern is a from plus context, filename, globOptions, info, preservePermissions, preserveTimestamps, to and transform — all documented under output.copy, which takes the same patterns.
• concurrency (number = 100): the maximum number of files read at the same time.
• stage (number = webpack.Compilation.PROCESS_ASSETS_STAGE_ADDITIONAL): the processAssets stage the files are copied at. At the default stage a copied file is minimized and compressed like every other asset; a later stage emits it after the taps that would have done so.

Usage

import webpack from "webpack";

export default {
  // ...
  plugins: [
    new webpack.CopyPlugin({
      patterns: [
        "static",
        { from: "img", to: "images" },
        { from: "licenses/*.txt", to: "licenses" },
      ],
      concurrency: 50,
    }),
  ],
};

Keeping a file out of the minimizer

A prebuilt file is already minimized, and running the minimizer over it again costs time for nothing. Mark it as minimized in its asset info and the minimizer leaves it alone:

import webpack from "webpack";

export default {
  // ...
  plugins: [
    new webpack.CopyPlugin({
      patterns: [
        {
          from: "*.min.js",
          context: "vendor",
          to: "vendor",
          info: { minimized: true },
        },
      ],
    }),
  ],
};

Merging copied assets

One source file becomes one asset, so combining several into one is a second pass over what the copy emitted — which any plugin can do. Copied assets carry copied: true in their asset info, which is how you pick them out:

compilation.hooks.processAssets.tap(
  {
    name: "MergeCopiedAssetsPlugin",
    stage: webpack.Compilation.PROCESS_ASSETS_STAGE_DERIVED,
  },
  () => {
    const assets = compilation
      .getAssets()
      .filter((asset) => asset.info.copied && /^licenses\//.test(asset.name))
      .toSorted((a, b) => (a.name < b.name ? -1 : 1));
    if (assets.length === 0) return;

    const merged = assets
      .map((asset) => `/* ${asset.name} */\n${asset.source.source()}`)
      .join("\n");

    compilation.emitAsset(
      "THIRD_PARTY_LICENSES.txt",
      new webpack.sources.RawSource(merged),
      { copied: true },
    );
    for (const asset of assets) compilation.deleteAsset(asset.name);
  },
);

DefinePlugin

The DefinePlugin replaces variables in your code with other values or expressions 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...
});

Usage

Each key passed into DefinePlugin is an identifier or multiple identifiers joined with ..

• If the value is a string it will be used as a code fragment.
• If the value isn't a string, it will be stringified (including functions).
• If the value is an object all keys are defined the same way.
• If you prefix 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");

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");

Feature Flags

Enable/disable features in production/development build using feature flags.

new webpack.DefinePlugin({
  NICE_FEATURE: JSON.stringify(true),
  EXPERIMENTAL_FEATURE: JSON.stringify(false),
});

Service URLs

Use a different service URL in production/development builds:

new webpack.DefinePlugin({
  SERVICE_URL: JSON.stringify("https://dev.example.com"),
});

Runtime values via runtimeValue

(fn: (context: { module: NormalModule, key: string, version: string | undefined }) => CodeValuePrimitive, options?: true | string[] | RuntimeValueOptions) => RuntimeValue

It is possible to define variables with values that rely on files and will be re-evaluated when such files change in the file system. This means webpack will rebuild when such watched files change.

There're two arguments for webpack.DefinePlugin.runtimeValue function:

• The first argument is the generator function above: it receives { module, key, version } and returns the value to be assigned to the definition.
• The second argument could either be an array of file paths to watch for or a true to flag the module as uncacheable. Since 5.26.0, it can also take an object argument with the following properties:
  • fileDependencies?: string[] A list of files the function depends on.
  • contextDependencies?: string[] A list of directories the function depends on.
  • missingDependencies?: string[] A list of not existing files the function depends on.
  • buildDependencies?: string[] A list of build dependencies the function depends on.
  • version?: string | () => string A version of the function.

import path from "node:path";
import { fileURLToPath } from "node:url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const fileDep = path.resolve(__dirname, "sample.txt");

new webpack.DefinePlugin({
  BUILT_AT: webpack.DefinePlugin.runtimeValue(Date.now, {
    fileDependencies: [fileDep],
  }),
});

The value of BUILT_AT would be the time at which the 'sample.txt' was last updated in the file system, e.g. 1597953013291.

DiagnosticsWebpackPlugin

This plugin only supports webpack >= 5.106.0 and Node.js >= 22.12.0.

This plugin runs linters, type checkers and other diagnostic tools over your sources during the webpack build and reports what they find as webpack errors and warnings.

It replaces eslint-webpack-plugin and stylelint-webpack-plugin: one plugin, one place to configure how problems are reported, and one pass over your project. Today it runs ESLint, Stylelint, oxlint, Biome and TypeScript; more linters and diagnostic tools are meant to be added the same way.

Getting Started

To begin, you'll need to install diagnostics-webpack-plugin:

npm install diagnostics-webpack-plugin --save-dev

or

yarn add -D diagnostics-webpack-plugin

or

pnpm add -D diagnostics-webpack-plugin

[!NOTE]

Install the tools you want to run as well — the plugin only requires the ones you enable. It supports eslint >= 9, stylelint >= 17, oxlint >= 1, @biomejs/biome >= 2 and typescript >= 5:

npm install eslint stylelint oxlint @biomejs/biome typescript --save-dev

Then add the plugin to your webpack configuration and enable a check for each language you want inspected:

import DiagnosticsPlugin from "diagnostics-webpack-plugin";

export default {
  // ...
  plugins: [
    new DiagnosticsPlugin({
      checks: [
        { use: "eslint", extensions: ["js", "mjs"] },
        { use: "stylelint", extensions: ["css", "scss"] },
      ],
    }),
  ],
  // ...
};

The package ships an ECMAScript build next to a CommonJS one, so a CommonJS configuration works just as well:

const DiagnosticsPlugin = require("diagnostics-webpack-plugin");

Options

The plugin options have three layers:

The options are checked against their schema from webpack's own validate hook, so a mistake is reported when webpack validates the rest of your configuration, and validate: false turns the check off along with webpack's.

Every check to run is an entry in checks, named by its use. The list may name the same tool more than once, so one instance can inspect two file sets under different configurations.

Every option

Anything else written in a checks entry is handed to the tool itself, so its own Node.js API options go next to these.

new DiagnosticsPlugin({
  // Plugin options
  context: "src",
  // Shared options, every check uses them unless it says otherwise
  reportAs: "warning", // report every check's results as warnings
  exclude: ["node_modules", "vendor"],
  // The checks to run, each with the options only it understands
  checks: [
    { use: "eslint", extensions: ["js", "ts"], fix: true },
    { use: "stylelint", extensions: ["css", "scss"], threads: true },
  ],
});

Plugin options

checks

• Type:

type checks = (string | ({ use: string | CheckAdapter } & Options))[];

• Default: none — this is the one option the plugin requires

The checks to run. An entry is the name of a built-in check, or an object naming it under use next to the options it takes, so these two are the same thing:

new DiagnosticsPlugin({ checks: ["eslint", { use: "eslint" }] });

Naming the same tool twice runs it twice, which is how one build checks two file sets under two configurations:

new DiagnosticsPlugin({
  checks: [
    { use: "eslint", files: "src", fix: true },
    { use: "eslint", files: "scripts", reportAs: "warning" },
  ],
});

use also takes an adapter of your own rather than a built-in name — see Adding a check.

context

• Type:

type context = string;

• Default: compiler.context

Base directory for linting. Every relative files and exclude pattern is resolved against it.

lintOnStart

• Type:

type lintOnStart = boolean;

• Default: true

Whether the first compilation lints every file it covers. Leave it alone and a build lints everything while a watch run lints everything once and then only what webpack rebuilds.

Set it to false to start a watch run quiet: nothing is linted until you touch a file, and only the modules webpack rebuilds are reported. A build is nothing but a first compilation, so it lints either way — the option cannot silence one.

Running the checks in one mode only

There is no option for this and none is needed: plugins ignores a falsy entry, so && decides whether the plugin is there at all. A configuration function is handed the --env values, and webpack-cli states the mode in them:

import DiagnosticsPlugin from "diagnostics-webpack-plugin";
import { defineConfig } from "webpack";

export default defineConfig((env) => ({
  plugins: [
    // Both values are read because each command sets only its own: `serve` sets
    // `WEBPACK_SERVE` and `--watch` sets `WEBPACK_WATCH`, so asking for one of
    // them misses the other way of watching. Read `WEBPACK_BUILD` instead to
    // check a build that runs once and leave a watch run alone.
    (env.WEBPACK_SERVE || env.WEBPACK_WATCH) &&
      new DiagnosticsPlugin({ checks: ["eslint", "stylelint"] }),
  ],
}));

This is worth doing when something else already lints the same files — a CI job running eslint ., or an editor — and the release build need not pay for it twice.

Two configurations at once

A client and a server configuration lint the same sources twice. Where two compilers run a check configured the same way over the same files — the whole of it for a check reading from the file system, whatever they both built for one reading the module graph — the second joins the run the first is making rather than starting its own, and both compilations report what it finds and watch what it read.

Over three hundred files with the typescript check, two compilers build one program rather than two: 1.52 s rather than 1.79 s, and 248 MB rather than 298 MB. What a compiler checks alone it still checks alone, and a check configured differently in the second configuration runs on its own.

Shared options

These can be set at the top level, where they apply to every check, or inside one check, where they apply to that check alone.

cache

• Type:

type cache = boolean;

• Default: true

The cache is enabled by default to decrease execution time.

An ESLint check doing typed linting keeps its results in a cache of its own instead of ESLint's: a cache keyed on one file's own contents cannot answer for a rule that read another, so a file whose import changed would be reported from before the change. Each result is kept against the file and everything it imports, however indirectly, together with the TypeScript config, global declarations and the ESLint config it was linted under, and a later build — a watch rebuild or a fresh webpack run — reuses it while all of that is the same. It is written next to cacheLocation, as <cacheLocation>.typed-results.json. With cache: false, every build lints every file.

cacheLocation

• Type:

type cacheLocation = string;

• Default: node_modules/.cache/diagnostics-webpack-plugin/.<tool>cache, and the directory node_modules/.cache/diagnostics-webpack-plugin/typescript for the TypeScript check

Specify the path to the cache location. Can be a file or a directory.

files

• Type:

type files = string | string[];

• Default: options.context

Specify directories, files, or globs. Must be relative to options.context. Directories are traversed recursively looking for files matching options.extensions. File and glob patterns ignore options.extensions.

Naming them says what to check, so every file they match is checked whether or not webpack built it — a module nothing imports yet, or one reached through a loader webpack resolves differently, is checked all the same. Leave it unset and a check reads whatever it reads by itself: ESLint the modules webpack built, Stylelint a walk of the context.

In a watch run the folder a check takes its files from is watched, so a file you add there is checked without anything else having to change — and for the typescript check, so is every folder the tsconfig.json include covers. A folder is only watched when the whole of it can be: webpack rebuilds on a change anywhere under one, so a folder holding what the build writes (output.path) or what the check itself leaves out (exclude, node_modules by default) is left alone rather than turning every write into a rebuild. Pointing files at your sources rather than leaving it at the project root is what makes it watchable.

extensions

• Type:

type extensions = string | string[];

• Default: 'js' for ESLint, ['css', 'scss', 'sass'] for Stylelint

Specify file extensions that should be checked.

exclude

• Type:

type exclude = string | string[];

• Default: 'node_modules', plus output.path for Stylelint

Specify the files/directories to exclude. Must be relative to options.context.

threads

• Type:

type threads = boolean | number | "auto";

• Default: "auto"

How many threads a check spreads its work over. "auto" takes one fewer than the machine has, leaving webpack the thread it builds on; a number asks for that many; false, 0 or 1 keeps the work on webpack's own thread.

A check that threads its own work is asked to, and one that cannot is run in a pool of workers — so the option means the same thing whatever is being checked, and a check added later gets it for nothing. ESLint threads its own work from 9.34.0 under flat config; Stylelint threads none of its own, so it is pooled. TypeScript reads a program whole rather than a file at a time, so it is run on one worker: what a thread buys it is webpack's own thread back.

Prefer "auto" over a count. A check sizes "auto" against the machine, where a fixed number can end up competing with webpack for the same cores: over three hundred modules on four of them, "auto" took about a fifth off the build while asking for three was no better than asking for none. A count above what the machine has is held to it, since asking for sixteen threads on four cores took twice as long as asking for none — the ceiling cannot save a number written against the tool itself, such as ESLint's concurrency, which is passed through as written.

Anything written against the tool itself wins — ESLint's own concurrency, say — and a check configured with a function, such as a formatter written in the configuration, is run on webpack's thread, because a function cannot be handed to a worker.

readsAcrossFiles

• Type:

type readsAcrossFiles = boolean;

• Default: read from the tool's configuration

Whether what a check reports of one file can turn on another — a type the file imports, an import cycle through it. A rebuild otherwise lints only what webpack rebuilt and reports every other file from its last run, which is wrong for such a check: an edit to one file can change what is true of the files importing it. So a rebuild of a check that reads across files lints the files that changed and every file importing one of them, however indirectly, and keeps the rest.

Which file imports which is read with the project's own TypeScript, through the tsconfig.json nearest each file, so an import type counts though a bundler drops it before webpack sees it — and this holds for every check, whatever tool it runs. A change that could reach files some other way — a declaration file nothing imports, a declare global, a config file, an import that resolves to nothing (a stylesheet, an image or another asset webpack bundles aside) — lints every file again, as does a project without TypeScript. There, an ESLint check with cache: true written down keeps ESLint's own cache, which answers for a file whose import changed from before the change.

A file changed while webpack watches reaches its importers only when what it shows them changes: the declarations it emits and what it imports. Edit the body of a function or a comment and only that file is linted again — told apart by ts.transpileDeclaration (TypeScript 5.5 and later), which needs no type checker and so answers only for a file whose exports say their own types, and only from the second edit of a file on, the first being what it is told from. Over three hundred modules in a chain, editing one halfway along took a typed-linting rebuild from 1.1–1.4 s to 0.16–0.2 s.

Left out, each check reads it from its tool's configuration:

Written down, it answers for the check whatever its configuration says — false for a Biome project using none of the rules that read other files, true for a check of your own that does not say:

new DiagnosticsPlugin({
  checks: [{ use: "biome", readsAcrossFiles: false }],
});

resourceQueryExclude

• Type:

type resourceQueryExclude = RegExp | RegExp[] | string | string[];

• Default: []

Specify the resource query to exclude. A string is read as the source of a regular expression, so "raw" and /raw/ mean the same thing. Only affects checks that read the module graph, such as ESLint.

fix

• Type:

type fix = boolean;

• Default: false

Will enable the autofix feature of the tool.

Be careful: this option will modify source files.

formatter

• Type:

type formatter = string | ((results: LintResult[]) => string);

• Default: the tool's own default formatter

Accepts the name of a formatter the tool ships, or a function that receives its results and returns the output as a string.

See the ESLint formatters and the Stylelint formatter option.

Errors and warnings

Every check reports its errors as webpack errors and its warnings as webpack warnings, which is what fails the build. reportAs overrides that.

reportAs

• Type:

type reportAs = Severity | { errors?: Severity; warnings?: Severity };
type Severity = "error" | "warning" | "log" | false;

• Default: unset — each result stays at the severity the check gave it

What a check reports its results as. One value covers its errors and its warnings alike; an object sets them apart, and a severity the object leaves out keeps its own:

new DiagnosticsPlugin({
  reportAs: { warnings: false }, // the errors alone
  checks: [{ use: "eslint" }],
});

"log" is for a check nobody should be stopped by yet. Its results reach webpack's log — the terminal, and stats.logging — rather than compilation.errors or compilation.warnings, so the build carries neither, stats.hasWarnings() stays false and a dev server overlays nothing. An outputReport is written either way.

new DiagnosticsPlugin({
  // the whole project is linted, and only the new check is advisory
  checks: [{ use: "eslint" }, { use: "typescript", reportAs: "log" }],
});

A check nothing can be reported from is one a watch rebuild does not wait for: every reportAs that leaves both errors and warnings off the compilation — "log", false, or an object spelling both out — with no outputReport to write. The first build still waits, since it is what tells the watcher which files the check reads. From the rebuild on, the check is run once the build is over rather than beside it, and what it finds is printed through webpack's infrastructure log rather than through stats.logging.

The work is moved out of the rebuild rather than off the machine: an edit arriving while such a check is still running waits for the rest of it, since a check holds the thread the build runs on. A report a newer rebuild has already overtaken is dropped, and a check never has two of its runs going at once — the next starts when the last has reported.

ignoreDiagnostics

• Type:

type ignoreDiagnostics =
  IgnoreOne | IgnoreOne[] | ((message: Message) => boolean);

type IgnoreOne = number | string | IgnoreMatch;

interface IgnoreMatch {
  file?: string | undefined;
  code?: string | undefined;
  severity?: "error" | "warning" | undefined;
}

interface Message {
  file?: string | undefined;
  code?: string | undefined;
  severity: "error" | "warning";
  text: string;
}

• Default: unset

What not to report. A linter's rule can be turned off in its own configuration and a TypeScript diagnostic cannot, so this is where one thing a check found is left out whichever check found it — for adopting a check on a project that is not clean yet, without turning the check off altogether.

new DiagnosticsPlugin({
  checks: [
    // TS2307 is `Cannot find module`, TS7016 an untyped dependency
    { use: "typescript", ignoreDiagnostics: [2307, 7016] },
    // a rule that has not been dealt with in one folder yet
    {
      use: "eslint",
      ignoreDiagnostics: { code: "no-unused-vars", file: "src/legacy/**" },
    },
  ],
});

A file is a glob matched against the path relative to context, as exclude is. Something a check reported of no file in particular — a configuration it could not read — is not a file's to leave out, so a match naming one keeps it.

What is left out is left out of everything the check reports, an outputReport included, and of the counts a formatter prints. A check shipped outside this package answers for its own results, so it reads this option once it says how (see Adding a check).

outputReport

• Type:

type outputReport =
  | boolean
  | {
      filePath?: string | undefined;
      formatter?: (string | ((results: LintResult[]) => string)) | undefined;
    };

• Default: false

Write the results to a file, for example a checkstyle xml file for use for reporting on Jenkins CI.

• filePath: path to the output report file, relative to output.path unless absolute.
• formatter: a different formatter for the output file; the default/configured formatter is used when none is passed in.

Set at the top level, every check appends its report to the same file. Set it inside a checks entry to give that check a file of its own.

new DiagnosticsPlugin({
  checks: [
    {
      use: "eslint",
      outputReport: { filePath: "eslint.json", formatter: "json" },
    },
    {
      use: "stylelint",
      outputReport: { filePath: "stylelint.json", formatter: "json" },
    },
  ],
});

ESLint

Run with { use: "eslint" }. It lints the files webpack builds, so only the modules that end up in the bundle are checked.

Alongside the shared options you can pass any ESLint Node.js API option — they are handed to the ESLint class as they are.

threads reaches ESLint as its own concurrency from 9.34.0 under flat config, and an older ESLint or an eslintrc one is pooled instead. Typed linting — a configuration with parserOptions.project or projectService — is the exception: every thread builds the whole TypeScript program again, and from cold on each rebuild, so it is linted on webpack's thread, where the program stays warm. Write concurrency yourself and that is what ESLint is given, whatever threads says. Threaded by ESLint, a check is handed every file at once when webpack is done building them rather than in batches while it builds: ESLint starts its workers and loads the configuration in each of them for every run, which over 1,500 files took a build from 13 s and 45 s of CPU to 8.5 s and 17 s. Note that webpack spells this idea parallelism, and uses the word concurrency for something else again — bounded work on one thread.

A rebuild lints only the files webpack rebuilt and reports the rest from the previous run, so lintOnStart is only worth setting to start a watch run quiet.

Typed linting is the exception, and it is read from your configuration rather than asked of you. Where parserOptions.project or parserOptions.projectService is set, what a rule reports of one file can turn on another — a type it imported, a declaration file something regenerated — so a file that did not itself change is not one whose last result still holds. A rebuild then lints the files that changed and every file importing one of them, however indirectly — see readsAcrossFiles — and ESLint's own cache gives way to one keyed on everything a file imports, since ESLint's is keyed on each file's own contents and would answer for a type it never read. Over three hundred modules, an edit near the bottom of the import tree took a rebuild from 2.0 s to 0.35 s, and one halfway up to 1.2 s. Across separate runs, a thousand-file project that took 10 s every time now takes 4 s once nothing it imports has changed, as fast as eslint-webpack-plugin's cache that can go stale.

configType

• Type:

type configType = "flat" | "eslintrc";

• Default: flat

Specify the type of configuration to use with ESLint.

• flat is the current standard configuration format.
• eslintrc is the legacy configuration format and has been officially deprecated.

The new configuration format is explained in its own documentation.

eslintrc needs an ESLint that still reads one: ESLint 9 does, ESLint 10 removed it, and the option stays for as long as this plugin supports 9. The check loads ESLint the same way wherever it runs it, in the build's own thread and in a worker of a pool alike, and the ESLint 9 job in CI checks both.

eslintPath

• Type:

type eslintPath = string;

• Default: eslint

Path to the eslint instance that will be used for linting.

If the eslintPath is a folder like the official ESLint, or you specify a formatter option, you don't have to install eslint.

Suppressions

Bulk suppressions are supported: enable ESLint's own applySuppressions, and point suppressionsLocation at the file if it is not the default eslint-suppressions.json.

new DiagnosticsPlugin({
  checks: [{ use: "eslint", applySuppressions: true }],
});

[!IMPORTANT]

ESLint resolves the suppressions file, and every path recorded inside it, against its own cwd — not against the plugin's context. Where the two differ, pass cwd to the check as well:

Copy

new DiagnosticsPlugin({
  context: "src",
  checks: [
    { use: "eslint", applySuppressions: true, cwd: import.meta.dirname },
  ],
});

Suppressions need ESLint 9.24 or later. ESLint 10 takes both options itself; below that they reach its CLI alone, so the plugin applies the suppressions after linting instead — the same file, the same paths, the same result.

Stylelint

Run with { use: "stylelint" }, and requires stylelint >= 17. It lints every file matching files and extensions on disk, whether or not webpack imported it, so a stylesheet nothing imports yet is still checked.

Alongside the shared options you can pass any Stylelint option — they are handed to stylelint.lint() as they are.

stylelintPath

• Type:

type stylelintPath = string;

• Default: stylelint

Path to the stylelint instance that will be used for linting.

oxlint

Run with { use: "oxlint" }, and requires oxlint >= 1. It lints the files webpack builds, as the ESLint check does, and reads whatever .oxlintrc.json oxlint finds for itself.

new DiagnosticsPlugin({ checks: ["eslint", "oxlint"] });

oxlint is a binary behind a Node entry rather than a library, so this check runs it and reads the JSON it answers with. Two things follow. Its severities are oxlint's own — a rule set to "error" in .oxlintrc.json is reported as a webpack error and one set to "warn" as a warning, and reportAs moves them from there as it does for every check. And the options this check does not name are not guessed at: write them as args, the flags oxlint itself documents.

Type-aware rules and the import plugin — import/no-cycle reports a file for what the files it imports import — answer for a file from others, so where args or the config turns them on, a rebuild lints again every file a change reaches. See readsAcrossFiles.

oxlintPath

• Type:

type oxlintPath = string;

• Default: oxlint

Path to the oxlint instance that will be used for linting.

configFile

• Type:

type configFile = string;

• Default: unset, leaving oxlint to find its own

Path to the .oxlintrc.json to lint with.

args

• Type:

type args = string[];

• Default: []

Arguments passed to oxlint as they are, for the flags this check does not name — ["--deny", "correctness"], say. Not --format: the check asks for JSON and formats the results itself, and oxlint declines being asked twice.

Biome

Run with { use: "biome" }, and requires @biomejs/biome >= 2. It checks the files webpack builds and reads whatever biome.json Biome finds for itself, reporting at Biome's own severities.

new DiagnosticsPlugin({ checks: ["biome"] });

Like the oxlint check this runs a binary and reads the JSON it answers with, which Biome calls an experimental reporter — a release of its own may move the shape, and it is the only reporter carrying the severities this check needs.

Biome's project and types rules — noImportCycles, noFloatingPromises — answer for a file from the files it imports, and which rules those are is not something its config says, so a rebuild lints again every file a change reaches. A project using none of them can write readsAcrossFiles: false to lint only what webpack rebuilt.

biomePath

• Type:

type biomePath = string;

• Default: @biomejs/biome

Path to the @biomejs/biome instance that will be used for checking.

command

• Type:

type command = "lint" | "check";

• Default: "lint"

Which of Biome's commands to run. "lint" runs the linter; "check" adds its formatting and assist diagnostics, so a badly formatted file is reported as well as one breaking a rule.

configFile

• Type:

type configFile = string;

• Default: unset, leaving Biome to find its own

Path to the biome.json to check with.

args

• Type:

type args = string[];

• Default: []

Arguments passed to Biome as they are, for the flags this check does not name. Not --reporter: the check asks for JSON and formats the results itself.

TypeScript

Run with { use: "typescript" }, and requires typescript >= 5. It type checks the program a tsconfig.json describes, so every file that config includes is checked whether or not webpack built it, and a type error in a module nothing imports yet is still reported. Emit is forced off: webpack writes the output.

new DiagnosticsPlugin({
  checks: [{ use: "typescript", configFile: "tsconfig.build.json" }],
});

Project references are read rather than built unless build says otherwise, which is what a tsconfig.json listing only references needs.

Two things differ from the linters. A diagnostic belongs to the program rather than to one file, so there is nothing to report a single file from. And extensions only decides which files make the check run at all; what is checked is whatever the config file includes.

A program is read whole, so threads buys it webpack's own thread back rather than a share of the work: the check runs on one worker while webpack builds, and is read where it is reported. Over a three-hundred-file solution beside three hundred modules that took the build from 2149 ms to 1920 ms and the module graph from 2004 ms to 385 ms, and an edit-to-report in watch from 259 ms to 203 ms. A small project pays the thread's start without much to hide behind it; threads: false keeps the work where webpack is.

While webpack watches, the program is kept and handed to the build after it, so a rebuild type checks what the change reaches rather than the project over again — about 30 ms rather than 300 over three hundred files, for the memory the program holds on to (some 50 MB there). A change to the config file, or to the compiler options given here, starts a new one. A rebuild for a file the program neither reads nor would pick up — a stylesheet, an image — reports what the last run found without asking the program at all.

Between runs, what the program found is kept in the cache: a .tsbuildinfo for each config file under node_modules/.cache/diagnostics-webpack-plugin/typescript, which the first program of the next run starts from, checking again only the files whose content changed and what they reach. Over three hundred modules a second webpack run went from 4.7 s and 12 s of CPU to 2.0 s and 6 s. A mode that writes keeps to the config file's own incremental instead, and cache: false starts every run from nothing.

Alongside the shared options you can pass any compiler option — they override what the config file sets, as --strict would on the command line.

skipLibCheck is the one most worth knowing about. The check follows the config file, so unless it says otherwise every declaration file the program reads is type checked too — TypeScript's own lib.*.d.ts and every package's types. Over three hundred modules that was 2.3 s of a 3.2 s check; with skipLibCheck: true it was 0.55 s. fork-ts-checker-webpack-plugin turns it on whatever the config file says, which is most of why it looks faster on a first build:

new DiagnosticsPlugin({
  checks: [{ use: "typescript", skipLibCheck: true }],
});

typescriptPath

• Type:

type typescriptPath = string;

• Default: typescript

Path to the typescript instance that will be used for checking.

configFile

• Type:

type configFile = string;

• Default: the nearest tsconfig.json at or above context

Path to the tsconfig.json that describes the program.

compilerOptions

• Type:

type compilerOptions = object;

• Default: unset

Compiler options overriding the ones the config file sets. The same as writing them at the top level of the check, and useful when a name collides with one of the plugin's own.

build

• Type:

type build = boolean;

• Default: false

Build the projects the config file references before reporting, the way tsc -b does. A tsconfig.json that only lists references describes an empty program of its own, so without this a solution reports nothing at all; with it, every project in the graph is checked in the order its references say.

new DiagnosticsPlugin({
  checks: [{ use: "typescript", build: true }],
});

A reference is read through the declarations the referenced project publishes, so building one is how the next is checked at all — the build therefore writes each project's .d.ts and its .tsbuildinfo, and nothing else. The JavaScript stays webpack's to write: a later tsc -b of your own still emits it. mode says so in full, and can say otherwise.

The cost is a tsc -b pass rather than the kept program the check uses otherwise. Over five projects and 205 files: 573 ms with nothing built yet, 4–8 ms when the solution is up to date, 258 ms after one file changed, and around 200 ms on every rebuild for as long as an error stands, since a project that fails is never up to date. Pair it with reportAs: "log" if you would rather a watch rebuild did not wait for that.

mode

• Type:

type mode = "readonly" | "write-tsbuildinfo" | "write-dts" | "write-references";

• Default: "write-dts" under build, "readonly" otherwise

What the check writes as well as reports. A check reports, so by default a program writes nothing at all and a solution writes only what the next project has to read.

new DiagnosticsPlugin({
  checks: [{ use: "typescript", build: true, mode: "write-references" }],
});

readonly under build is not the compiler's noEmit, which tsc -b refuses with TS6310: the build runs and its output is kept where only that build can read it, so a project still finds the declarations of the one it references while your working tree is left alone.

diagnosticOptions

• Type:

interface diagnosticOptions {
  syntactic?: boolean | undefined;
  semantic?: boolean | undefined;
  declaration?: boolean | undefined;
  global?: boolean | undefined;
}

• Default: every kind reported

Which kinds of diagnostic to report. Turning one off asks TypeScript for less rather than dropping what it answered, so it is also the one filter that saves the work — semantic: false is what makes a check that only wants syntax errors cheap.

declaration is asked of a project compiled with declaration or composite, and a rebuild works it out again only for the files a change reached — the ones TypeScript type checks again — rather than emitting the declarations of the whole program each time: over 300 files, a rebuild went from 360–490 ms to 150 ms.

new DiagnosticsPlugin({
  // webpack's own parser reports a syntax error in a file it builds
  checks: [{ use: "typescript", diagnosticOptions: { syntactic: false } }],
});

What the tsconfig.json itself is wrong about is reported whatever is turned off here: with the config file misread, nothing below it would be answering the right question. build reports the whole of what it finds either way, since a solution is built rather than asked kind by kind.

fork-ts-checker-webpack-plugin spells this option the same way, with semantic alone on by default.

Making it faster

Most of what a check costs is its tool's, and a few settings outside the plugin decide how much of it is paid again. Each was measured on four cores.

skipLibCheck for the TypeScript check. Type checking every declaration file the program reads is most of a first build; see TypeScript.

cacheStrategy: "content" where CI restores the cache. ESLint keys its cache on each file's time and size by default, and a fresh checkout gives every file a new time, so a cache restored in CI answers for nothing. Keyed on what the files hold, it does:

new DiagnosticsPlugin({
  checks: [{ use: "eslint", cacheStrategy: "content" }],
});

Over 1,500 files, a build after touching every one of them took 9.9 s with the default and 5.9 s with content, the same as a build with nothing touched. Typed linting keeps its results against what files hold already.

NODE_COMPILE_CACHE for Node 22.1 and later. ESLint, typescript-eslint and TypeScript are a lot of JavaScript for Node to compile on every start; the environment variable keeps what it compiled on disk:

NODE_COMPILE_CACHE=node_modules/.cache/node-compile webpack

A typed-linting build of three hundred modules that found its results in the cache went from 2.34–2.60 s and 3.7–4.0 s of CPU to 2.18–2.20 s and 3.5–3.6 s.

Adding a check

A use may also be an adapter of its own rather than a built-in name, so a check can ship as its own package without an entry in this one:

new DiagnosticsPlugin({
  checks: [
    { use: require("diagnostics-webpack-plugin-typescript"), strict: true },
  ],
});

Such an adapter is an object with a name, and a create returning the five functions the plugin drives it through — what to lint, what came back, which results are errors and which warnings, how to format them, and what to release afterwards. It splits its results by their own severity and nothing else; reportAs is applied to what it returns:

module.exports = {
  name: "made-up",
  // "modules" lints the files webpack built, "glob" every file matching `files`
  filesSource: "glob",
  // Merged under the options the user passes, and under the shared options
  defaults: { extensions: ["ts"] },
  async create({ key, options, compilation }) {
    return {
      lintFiles: async (files) => runTheTool(files),
      getResults: async (results) => results,
      splitResults: (results) => ({ errors: results, warnings: [] }),
      getFormatter: async (formatter) => async (results) => format(results),
      cleanup: async () => {},
    };
  },
};

label, filesSource, defaults, defaultExclude and schema are optional; the plugin fills in the defaults of a module-scanning check that excludes node_modules.

An adapter whose results come per file says which file with resultPath(result), and a rebuild then lints only what changed. One whose tool reads other files to answer for one says so with readsAcrossFiles(compiler, options), and the plugin lints again every file a change reaches through its own import graph — or through the adapter's affectedFiles(compiler, files, changed), where it knows better. An adapter is handed files in batches while webpack builds, so that its tool starts early; one whose tool pays for every run it starts — workers, configuration — says lintsOnce(options) and is handed them all at once instead.

Migrating

Both plugins become one, and every option they had is still here. What changed is where an option is written and how the four that decided severity are spelled.

Where an option goes. context, lintOnStart and checks are the plugin's own and stay at the top level. Everything else is shared: write it at the top level to cover every check, or inside a checks entry to cover that one. configType, eslintPath and stylelintPath belong to a single check and go in its entry.

Severity is one option. emitError, emitWarning, failOnError, failOnWarning and quiet are reportAs, because reporting a result as a webpack error is what fails the build:

The build is no longer aborted from inside the plugin. A result reported as a webpack error fails the build the way every other webpack error does — stats.hasErrors() is true and the CLI exits non-zero — and the assets are still written. Nothing about severity depends on mode any more.

Requirements. Node >= 22.12, webpack >= 5.106, and ESLint 9 or 10 / Stylelint 17 for whichever checks you run.

From eslint-webpack-plugin

-const ESLintPlugin = require("eslint-webpack-plugin");
+const DiagnosticsPlugin = require("diagnostics-webpack-plugin");

 module.exports = {
   plugins: [
-    new ESLintPlugin({ extensions: ["js"], fix: true }),
+    new DiagnosticsPlugin({
+      checks: [{ use: "eslint", extensions: ["js"], fix: true }],
+    }),
   ],
 };

Every option eslint-webpack-plugin accepted, and where it is now:

Any other option is passed to ESLint itself, as before.

From stylelint-webpack-plugin

-const StylelintPlugin = require("stylelint-webpack-plugin");
+const DiagnosticsPlugin = require("diagnostics-webpack-plugin");

 module.exports = {
   plugins: [
-    new StylelintPlugin({ extensions: ["css"], threads: true }),
+    new DiagnosticsPlugin({
+      checks: [{ use: "stylelint", extensions: ["css"], threads: true }],
+    }),
   ],
 };

Every option stylelint-webpack-plugin accepted, and where it is now:

Any other option is passed to Stylelint itself, as before. Two more things changed for Stylelint alone:

• Stylelint 17 or later is required. stylelint-webpack-plugin accepted 13 through 17; the merged plugin drops the older majors rather than carrying their compatibility branches forward. Stylelint 17 itself needs Node >= 20.19.
• Errors and warnings are no longer swapped. failOnError: false used to report errors as webpack warnings, and failOnWarning: true to report warnings as webpack errors. Each result now keeps its own severity unless reportAs says otherwise — which is what those two spellings in the table above do, explicitly.

fix is a documented option now rather than one passed through to Stylelint unnamed. resourceQueryExclude is shared but has no effect here: it reads the query of a module webpack built, and Stylelint is given the files matching files instead.

Running both

The two plugins become one instance, and options they had in common are written once:

 module.exports = {
   plugins: [
-    new ESLintPlugin({ context: "src", failOnError: true, extensions: ["js"] }),
-    new StylelintPlugin({ context: "src", failOnError: true, extensions: ["css"] }),
+    new DiagnosticsPlugin({
+      context: "src",
+      checks: [
+        { use: "eslint", extensions: ["js"] },
+        { use: "stylelint", extensions: ["css"] },
+      ],
+    }),
   ],
 };

From fork-ts-checker-webpack-plugin

The typescript check does what that plugin does — type check the program a tsconfig.json describes, rather than the files webpack happens to build — and is written as one entry in checks:

-const ForkTsCheckerWebpackPlugin = require("fork-ts-checker-webpack-plugin");
+const DiagnosticsPlugin = require("diagnostics-webpack-plugin");

 module.exports = {
   plugins: [
-    new ForkTsCheckerWebpackPlugin({
-      typescript: { configFile: "tsconfig.build.json", build: true },
-    }),
+    new DiagnosticsPlugin({
+      checks: [
+        { use: "typescript", configFile: "tsconfig.build.json", build: true },
+      ],
+    }),
   ],
 };

The check runs on a worker thread rather than in a process of its own. That plugin forks one, which is why it has a memoryLimit and a profile; a thread shares the build's heap and its copy of TypeScript, so neither is needed here. The program is kept between rebuilds either way. What that costs and saves is under the TypeScript check.

Over a generated 300-file project, three runs of each:

The time is the same within the run-to-run spread; the memory is not, and that is the thread rather than anything clever.

It is a drop-in, and was checked as one against a project neither of us wrote — the fork-ts-checker-webpack-plugin example that ts-loader ships, which is React and TSX through ts-loader. Swapping the plugin for { use: "typescript" } and nothing else reported the same TS2322 at the same line and column. Three things to expect while doing it:

• webpack must be 5.106 or newer, which is what the plugin requires at all.
• npm refuses to install alongside ESLint 8. The eslint peer here is optional but ranged ^9 || ^10, and npm resolves an optional peer it can see, so a project pinned to 8 needs its ESLint updated — or --legacy-peer-deps — even when no ESLint check is configured.
• fork-ts-checker-notifier-webpack-plugin has nothing to listen to. It taps that plugin's own hooks, so it goes when that plugin does.

Running it next to a linter is one plugin rather than two, with one place to say how what they find is reported:

new DiagnosticsPlugin({
  checks: [{ use: "eslint" }, { use: "typescript" }],
});

Changelog

Changelog

Contributing

We welcome all contributions!

If you're new here, please take a moment to review our contributing guidelines.

CONTRIBUTING

License

MIT

DllPlugin

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 configuration 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.)
• format (boolean = false): If true, manifest json file (output) will be formatted.
• name: name of the exposed dll function (TemplatePaths: [fullhash], [chunkhash], [contenthash], & [name] )
• path: absolute path to the manifest json file (output)
• entryOnly (boolean = true): if true, only entry points will be exposed
• type: type of the dll bundle

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)
• extensions: Extensions used to resolve modules in the dll bundle (only used when using 'scope').
• manifest : an object containing content and name or a string to the absolute path of the JSON manifest to be loaded upon compilation
• content (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 dll
• sourceType (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.

Modes

This plugin can be used in two different modes, scoped and mapped.

Scoped Mode

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

Mapped Mode

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, import _ from "lodash"/require('lodash') and import abs from "./abc"/require('./abc') will be used from the dll, rather than building them into the main bundle.

Usage

webpack.vendor.config.js

import path from "node:path";
import { fileURLToPath } from "node:url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

new webpack.DllPlugin({
  context: import.meta.dirname,
  name: "[name]_[fullhash]",
  path: path.join(__dirname, "manifest.json"),
});

webpack.app.config.js

import path from "node:path";
import { fileURLToPath } from "node:url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

new webpack.DllReferencePlugin({
  context: __dirname,
  manifest: path.join(__dirname, "manifest.json"),
  scope: "xyz",
  sourceType: "commonjs2",
});

Examples

Vendor and User

Two separate example folders. Demonstrates scope and context.

References

Source

• DllPlugin source
• DllReferencePlugin source
• DllEntryPlugin source
• DllModuleFactory source
• ManifestPlugin source

Tests

• DllPlugin creation test
• DllPlugin without scope test
• DllReferencePlugin use Dll test

EnvironmentPlugin

The EnvironmentPlugin is shorthand for using the DefinePlugin on process.env keys.

Usage

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),
  // since webpack 5.103.0
  "import.meta.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV),
  "import.meta.env.DEBUG": JSON.stringify(process.env.DEBUG),
});

Usage with default values

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

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");
}

Use Case: Git Version

The following EnvironmentPlugin configuration provides process.env.GIT_VERSION (such as "v5.4.0-2-g25139f57f") and process.env.GIT_AUTHOR_DATE (such as "2020-11-04T12:25:16+01:00") corresponding to the last Git commit of the repository:

import childProcess from "node:child_process";

function git(command) {
  return childProcess.execSync(`git ${command}`, { encoding: "utf8" }).trim();
}

new webpack.EnvironmentPlugin({
  GIT_VERSION: git("describe --always"),
  GIT_AUTHOR_DATE: git("log -1 --format=%aI"),
});

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

EvalSourceMapDevToolPlugin

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

This plugin wraps every module in an eval() call with its source map appended as a data URL, so no .map files are emitted. It accepts the same options object as the SourceMapDevToolPlugin, but the options that describe a separate source map file — filename, fileContext and publicPath — have nothing to name here and are ignored, as is a function-valued append.

Options

The following options are supported:

type Matcher =
  | string
  | RegExp
  | ((name: string) => boolean)
  | (string | RegExp | ((name: string) => boolean))[];

A string matches by prefix, a RegExp by test, and a function is called with the name and returns whether it matches.

• test (Matcher): Generate source maps for modules whose path matches the given value. There is no default: all modules get source maps unless test, include or exclude restrict them. It matches the module's own path, not the name of the chunk it ends up in, so it cannot be used to exclude a whole entry point or bundle.
• include (Matcher): Include source maps for module paths that match the given value.
• exclude (Matcher): Exclude modules that match the given value from source map generation.
• 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.
• ignoreList (Matcher): Decide whether to ignore source files that match the specified value in source maps.
• module (boolean): Indicates whether loaders should generate source maps (defaults to true).
• moduleFilenameTemplate (string): See output.devtoolModuleFilenameTemplate.
• columns (boolean): Indicates whether column mappings should be used (defaults to true).
• namespace (string): Namespace prefix to allow multiple webpack roots in the devtools. See output.devtoolNamespace.
• noSources = false (boolean): Prevents the source file content from being included in the source map.
• sourceRoot (string): Provide a custom value for the sourceRoot property in source maps.
• debugIds (boolean): If true, unique ids will be emitted in source and sourcemaps which streamlines identifying sourcemaps across different builds. See the TC39 sourcemap debug ID proposal for more details.

Examples

The following examples demonstrate some common use cases for this plugin.

Basic Use Case

You can use the following code to replace the configuration option devtool: eval-source-map with an equivalent custom plugin configuration:

export default {
  // ...
  devtool: false,
  plugins: [new webpack.EvalSourceMapDevToolPlugin({})],
};

Exclude Vendor Maps

The following code would exclude source maps for any module coming from node_modules:

new webpack.EvalSourceMapDevToolPlugin({
  exclude: /node_modules/,
});

HashedModuleIdsPlugin

This plugin will cause hashes to be based on the relative path of the module, generating a four character string as the module id.

new webpack.ids.HashedModuleIdsPlugin({
  // Options...
});

Options

This plugin supports the following options:

• context: The context directory (absolute path) for creating names.

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

  5.102.1+

  In addition to standard Node.js encodings, this plugin also supports 'base64url', which is useful for generating URL-safe hash values. The custom bases ('base26', 'base32', 'base36', 'base49', 'base52', 'base58', 'base62') are only available for output.hashDigest.

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

Usage

Here's an example of how this plugin might be used:

import path from "node:path";
import { fileURLToPath } from "node:url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

new webpack.ids.HashedModuleIdsPlugin({
  context: __dirname,
  hashFunction: "sha256",
  hashDigest: "hex",
  hashDigestLength: 20,
});

Using URL-safe encoding (5.102.1+):

import path from "node:path";
import { fileURLToPath } from "node:url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

new webpack.ids.HashedModuleIdsPlugin({
  context: __dirname,
  hashFunction: "md4",
  hashDigest: "base64url", // URL-safe encoding
  hashDigestLength: 8,
});

HotModuleReplacementPlugin

Enables Hot Module Replacement, otherwise known as HMR.

Basic Usage

Enabling HMR is straightforward; the plugin takes no options.

new webpack.HotModuleReplacementPlugin();

IgnorePlugin

IgnorePlugin prevents the generation of modules for import or require calls matching the regular expressions or filter functions.

Using regular expressions

• resourceRegExp: A RegExp to test the resource against.
• contextRegExp: (optional) A RegExp to test the context (directory) against.

new webpack.IgnorePlugin({ resourceRegExp, contextRegExp });

Using filter functions

• checkResource (resource, context) A Filter function that receives resource and context as arguments, must return boolean.

new webpack.IgnorePlugin({
  checkResource(resource) {
    // do something with resource
    return true | false;
  },
});

Example of ignoring Moment Locales

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({ resourceRegExp: /moment\/locale\// });

Rather, because moment imports with this code:

import(`./locale/${name}`);

// or

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.

Internal webpack plugins

This is a list of plugins which are used by webpack internally.

Categories of internal plugins:

• environment
• compiler
• entry
• output
• source
• optimize

environment

Plugins affecting the environment of the compiler.

NodeEnvironmentPlugin

webpack.node.NodeEnvironmentPlugin()

Applies Node.js style filesystem to the compiler.

compiler

Plugins affecting the compiler

MemoryCachePlugin

MemoryCachePlugin()

Adds a cache to the compiler, where modules are cached in memory.

ProgressPlugin

ProgressPlugin(handler)

Hook into the compiler to extract progress information. The handler must have the signature (percentage: number, message: string) => void. Percentage is called with a value between 0 and 1, where 0 indicates the start and 1 the end.

RecordIdsPlugin

RecordIdsPlugin()

Saves and restores module and chunk ids from records.

entry

Plugins, which add entry chunks to the compilation.

EntryPlugin

EntryPlugin(context, entry, options)

Adds an entry chunk on compilation. The chunk is named options.name and contains only one module (plus dependencies). The module is resolved from entry in context (absolute path).

PrefetchPlugin

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

output

JsonpTemplatePlugin

web/JsonpTemplatePlugin()

Chunks are wrapped into JSONP-calls. A loading algorithm is included in entry chunks. It loads chunks by adding a <script> tag.

It takes no options and sets output.chunkLoading to 'jsonp'. It is configured via the output options:

output.chunkLoadingGlobal is the JSONP function.

output.publicPath is used as path for loading the chunks.

output.chunkFilename is the filename under that chunks are expected.

NodeTemplatePlugin

node/NodeTemplatePlugin(options)

Chunks are wrapped into Node.js modules exporting the bundled modules. The entry chunks loads chunks by requiring them.

options.asyncChunkLoading (boolean) selects 'async-node' instead of 'require' as output.chunkLoading.

LibraryTemplatePlugin

LibraryTemplatePlugin(name, target)

The entries chunks are decorated to form a library name of type type.

WebWorkerTemplatePlugin

webworker/WebWorkerTemplatePlugin()

Chunks are loaded by importScripts. Else it's similar to JsonpTemplatePlugin.

It takes no options and sets output.chunkLoading to 'import-scripts'.

EvalDevToolModulePlugin

EvalDevToolModulePlugin(options)

Decorates the module template by wrapping each module in a eval annotated with a //# sourceURL= comment (options.sourceUrlComment, defaults to //# sourceURL=[url]).

SourceMapDevToolPlugin

SourceMapDevToolPlugin(options)

Decorates the templates by generating a SourceMap for each chunk.

options.filename the filename template of the SourceMap. [fullhash], [name], [id], [file] and [base] are replaced. If this option is missing, the SourceMap will be inlined as DataUrl.

options.append, options.moduleFilenameTemplate, options.fallbackModuleFilenameTemplate and the remaining options are described on the SourceMapDevToolPlugin page.

HotModuleReplacementPlugin

HotModuleReplacementPlugin()

Add support for hot module replacement. Decorates the templates to add runtime code. Adds module.hot API.

It takes no options and reads the following output options:

output.hotUpdateChunkFilename the filename for hot update chunks.

output.hotUpdateMainFilename the filename for the hot update manifest.

output.hotUpdateGlobal the global function name for loading hot updates.

source

Plugins affecting the source code of modules.

APIPlugin

Makes the __webpack_* variables (__webpack_public_path__, __webpack_require__, __webpack_modules__, __webpack_chunk_load__, __webpack_hash__, __webpack_nonce__, ...) accessible in modules and maps require.onError to the runtime's error handler (__webpack_require__.oe).

CompatibilityPlugin

Ensures compatibility with other module loaders by rewriting legacy patterns: browserify-style require delegators, user code that declares its own __webpack_require__, and hashbang lines.

ConstPlugin

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:

• The ones performed by Terser
• The ones performed by webpack

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

ProvidePlugin(definitions)

For each name: request entry in definitions, if name is used in a module it is filled by a module loaded by import ... from <request>/import(<request>)/require(<request>).

NodeStuffPlugin

NodeStuffPlugin(options)

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.

RequireJsStuffPlugin

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.

NodeSourcePlugin

node/NodeSourcePlugin()

This plugin is a no-op kept for backward compatibility. webpack 5 no longer polyfills Node.js core modules or globals such as process and Buffer.

NodeTargetPlugin

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.

AMDPlugin

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.

CommonJsPlugin

dependencies/CommonJsPlugin

Provides CommonJs-style require to modules.

RequireContextPlugin

dependencies/RequireContextPlugin()

Provides require.context. Alternative requests for files are derived from the configured resolve options (modules, extensions, mainFiles, enforceExtension).

RequireEnsurePlugin

dependencies/RequireEnsurePlugin()

Provides require.ensure.

RequireIncludePlugin

dependencies/RequireIncludePlugin()

Provides require.include.

DefinePlugin

DefinePlugin(definitions)

Define constants for identifier.

definitions is an object.

optimize

Note that all plugins under webpack.optimize namespace should only be used when mode set to 'none'. Otherwise you might get into trouble where plugins are applied twice.

LimitChunkCountPlugin

optimize/LimitChunkCountPlugin(options)

Merge chunks limit chunk count is lower than options.maxChunks.

options.chunkOverhead and options.entryChunkMultiplicator are still accepted but no longer have any effect.

Chunks that reduce the total size the most are merged first. If multiple combinations are equal the minimal merged size wins.

MergeDuplicateChunksPlugin

optimize/MergeDuplicateChunksPlugin()

Chunks with the same modules are merged.

RemoveEmptyChunksPlugin

optimize/RemoveEmptyChunksPlugin()

Chunks that contain no modules (and are neither runtime nor entry chunks) are removed.

MinChunkSizePlugin

optimize/MinChunkSizePlugin({ minChunkSize })

Merges chunks until each chunk has the minimum size of minChunkSize.

ModuleConcatenationPlugin

See the ModuleConcatenationPlugin page for details.

FlagIncludedChunksPlugin

optimize/FlagIncludedChunksPlugin()

Adds chunk ids of chunks which are included in the chunk. This eliminates unnecessary chunk loads.

RealContentHashPlugin

optimize/RealContentHashPlugin()

When optimization.realContentHash option is enabled, webpack will apply RealContentHashPlugin to compiler internally.

Hook

RealContentHashPlugin provides a updateHash 5.8.0+ hook for customizing hash updating:

import webpack from "webpack";

const { RealContentHashPlugin } = webpack.optimize;
// ...
compiler.hooks.compilation.tap("MyPlugin", (compilation) => {
  const hooks = RealContentHashPlugin.getCompilationHooks(compilation);
  hooks.updateHash.tap("MyPlugin", (content, oldHash) => {
    // you can calculate the hash here as you wish
  });
});

LimitChunkCountPlugin

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

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

import webpack from "webpack";

export default {
  // ...
  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 instead.

ManifestPlugin

The built-in ManifestPlugin generates one asset manifest for your build. Port from WebpackManifestPlugin.

webpack.config.js

new webpack.ManifestPlugin({
  // options...
});

Options

entrypoints

boolean = true

Enables generation of the entrypoints section in the manifest.

When entrypoints is enabled and one entry uses dependOn

webpack.config.js

export default {
  entry: {
    entry1: {
      import: "./src/file_1.js",
      dependOn: "entry2",
    },
    entry2: "./src/file_2.js",
  },
  plugins: [
    new webpack.ManifestPlugin({
      filename: "manifest.json",
    }),
  ],
};

The resulting manifest will contain the parent/child relationship map

manifest.json

{
  "entrypoints": {
    "entry1": {
      "imports": ["entry1.js"],
      "parents": ["entry2"]
    },
    "entry2": {
      "imports": ["entry2.js"]
    }
  }
}

filename

string = manifest.json

Specifies the filename of the output file on disk. By default the plugin will emit manifest.json inside the output.path directory.

filter

(item: ManifestItem) => boolean

Allows filtering the files which make up the manifest.

generate

(manifest: ManifestObject) => ManifestObject

Receives the manifest object, modifies it, and returns the modified manifest.

prefix

string = '[publicpath]'

Specifies a path prefix for all keys in the manifest.

serialize

(manifest: ManifestObject) => string = (manifest) => JSON.stringify(manifest, null, 2)

Receives the manifest object and returns the manifest string.

Use serialize to output other formats, for example YAML:

new webpack.ManifestPlugin({
  serialize(manifest) {
    return YAML.stringify(manifest, 4);
  },
});

Plugins

Webpack has a rich plugin interface. Most of the features within webpack itself use this plugin interface. This makes webpack flexible.

The plugins below are grouped by what they do. Most ship with webpack itself and are used as new webpack.SomePlugin(); the ones whose page lives under a *-webpack-plugin name are separate packages to install first.

Sources and modules

Output and assets

Chunks and optimization

Module Federation

Development and diagnostics

For more third-party plugins, see the list from awesome-webpack.

MergeDuplicateChunksPlugin

Merges chunks that contain the same modules. This plugin is enabled by default as part of webpack's internal optimizations. Exporting it publicly allows developers to configure the stage at which merging occurs — useful when chunk merging needs to run after SplitChunksPlugin.

new webpack.optimize.MergeDuplicateChunksPlugin({
  // Options...
});

Options

stage

number

Controls the optimization stage at which duplicate chunk merging runs. By default, merging occurs before SplitChunksPlugin. Setting a stage greater than 10 (the stage of SplitChunksPlugin) causes merging to run after it; a value of 10 still runs before it because user plugins are applied first. The built-in instance (stage -10) stays active, so this adds a second merging pass.

webpack.config.js

import webpack from "webpack";

export default {
  // ...
  plugins: [
    new webpack.optimize.MergeDuplicateChunksPlugin({
      stage: 11, // run after SplitChunksPlugin (stage 10)
    }),
  ],
};

MinChunkSizePlugin

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

MinimizerWebpackPlugin

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 option and target the right files with test.

JavaScript minimizers:

• 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 — MinimizerPlugin.uglifyJsMinify. ES5-only minifier, useful when you specifically need UglifyJS-compatible output. Requires npm install --save-dev uglify-js.
• @swc/core — MinimizerPlugin.swcMinify. A very fast Rust-based JavaScript/TypeScript minifier. Requires npm install --save-dev @swc/core.
• 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:

• webpack's own — webpack.html.syntax.htmlMinify. Ships with webpack (>= 5.111.0), so it needs no extra dependency, and it is the one that minifies what a document nests: an inline <style>, every style="", a <script>, an <svg> subtree. See webpack's own minimizers.
• html-minifier-terser — MinimizerPlugin.htmlMinifierTerser. JavaScript-based, no native dependency. Requires npm install --save-dev html-minifier-terser.
• @swc/html — MinimizerPlugin.swcMinifyHtml (full HTML documents) and MinimizerPlugin.swcMinifyHtmlFragment (HTML fragments, e.g. <template> content). Very fast Rust-based platform for the Web. Requires npm install --save-dev @swc/html.
• @minify-html/node — MinimizerPlugin.minifyHtmlNode. A Rust HTML minifier optimised for speed and effectiveness. Requires npm install --save-dev @minify-html/node.

CSS minimizers:

• webpack's own — webpack.css.syntax.cssMinify. Ships with webpack (>= 5.111.0), so it needs no extra dependency, and it minifies the CSS a stylesheet or a document nests. See webpack's own minimizers.
• cssnano — MinimizerPlugin.cssnanoMinify. Built on top of PostCSS. Requires npm install --save-dev cssnano postcss.
• csso — MinimizerPlugin.cssoMinify. A CSS minifier with structural optimisations. Requires npm install --save-dev csso.
• clean-css — MinimizerPlugin.cleanCssMinify. A widely-used CSS optimiser. Requires npm install --save-dev clean-css.
• esbuild — MinimizerPlugin.esbuildMinifyCss. Very fast CSS minification using esbuild's CSS loader. Requires npm install --save-dev esbuild.
• lightningcss — MinimizerPlugin.lightningCssMinify. A Rust-based CSS parser, transformer, and minifier. Requires npm install --save-dev lightningcss.
• @swc/css — MinimizerPlugin.swcMinifyCss. A very fast Rust-based CSS minifier. Requires npm install --save-dev @swc/css.

Image minimizers:

• 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 — MinimizerPlugin.svgoMinify. Minifies SVG, including an asset/inline SVG that no test can match. Requires npm install --save-dev svgo.
• imagemin — MinimizerPlugin.imageminMinify. Runs the imagemin plugins you name. Requires npm install --save-dev imagemin plus each plugin. Pair it with MinimizerPlugin.imageminGenerate under generate when a plugin converts the format, since only that can rename the asset.
• @napi-rs/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.

Transport encodings:

• zlib and anything shaped like it — MinimizerPlugin.compress. Compresses an asset so a server can serve it under Content-Encoding. Takes algorithm — a zlib function's name (gzip, brotliCompress, deflate, zstdCompress, …) or one of your own — and compressionOptions for it, and needs no extra dependency. Give it to minify to compress an asset in place, or to generate as an asset generator to write the compressed file beside the original; either way it puts itself after the minimizers, through a getStage of its own.

All of the non-default minimizers are declared as optional peer dependencies — install only the ones you actually use. One plugin instance covers several languages at once: give minify an array and each minimizer is offered only the assets its own filter accepts, so JS, CSS, HTML and JSON share a single worker pool (see 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:

npm install minimizer-webpack-plugin --save-dev

or

yarn add -D minimizer-webpack-plugin

or

pnpm add -D minimizer-webpack-plugin

Then add the plugin to your webpack configuration. For example:

webpack.config.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 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
• include
• exclude
• parallel
• minify
• minimizerOptions (deprecated)
• generate
• extractComments

test

Type:

type test = string | RegExp | (string | RegExp)[];

Default: /\.m?js(\?.*)?$/i

Test to match files against.

webpack.config.js

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new MinimizerPlugin({
        test: /\.js(\?.*)?$/i,
      }),
    ],
  },
};

include

Type:

type include = string | RegExp | (string | RegExp)[];

Default: undefined

Files to include.

webpack.config.js

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

exclude

Type:

type exclude = string | RegExp | (string | RegExp)[];

Default: undefined

Files to exclude.

webpack.config.js

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

parallel

Type:

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, #202).