diagnostics-webpack-plugin

This plugin only supports webpack 5 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 and Stylelint; more linters and diagnostic tools are meant to be added the same way.

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

npm install eslint stylelint --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");

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.

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

type context = string;

• Default: compiler.context

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

type lintDirtyModulesOnly = boolean;

• Default: false

Lint only changed files, skipping the initial lint on build start.

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.

type cache = boolean;

• Default: true

The cache is enabled by default to decrease execution time.

type cacheLocation = string;

• Default: node_modules/.cache/diagnostics-webpack-plugin/.<tool>cache

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

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.

type extensions = string | string[];

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

Specify file extensions that should be checked.

type exclude = string | string[];

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

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

type resourceQueryExclude = RegExp | RegExp[];

• Default: []

Specify the resource query to exclude. Only affects checks that read the module graph, such as ESLint.

type fix = boolean;

• Default: false

Will enable the autofix feature of the tool.

Be careful: this option will modify source files.

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.

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

type reportAs = Severity | { errors?: Severity; warnings?: Severity };
type Severity = "error" | "warning" | 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" }],
});

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

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. concurrency is worth knowing about: it spreads a lint across worker threads, and ESLint warns on the runs where doing so costs more than it saves, so measure your own project rather than turning it on by default.

A rebuild lints only the files webpack rebuilt and reports the rest from the previous run, so lintDirtyModulesOnly is only worth setting to skip the first lint entirely.

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.

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.

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

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.

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.

type stylelintPath = string;

• Default: stylelint

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

type threads = boolean | number;

• Default: false

Set to true for an auto-selected pool size based on the number of CPUs. Set to a number greater than 1 to set an explicit pool size.

Set to false, 1, or less to disable and only run in the main process.

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.

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, lintDirtyModulesOnly 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, stylelintPath and threads 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, and ESLint 9 or 10 / Stylelint 17 for whichever checks you run.

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

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

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

Changelog