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.

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 linters you want to run as well — the plugin only requires the ones you enable. It supports eslint >= 9 and stylelint >= 17:

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

Options

The plugin options have three layers:

Layer	Where it goes	What it covers
Plugin	Top level only	How the plugin schedules its work, for every check at once.
Shared	Top level or in a `checks` entry	Which files are linted and how problems are reported. An entry overrides what it sets.
Check	In a `checks` entry	Options only that tool understands, plus everything its own Node.js API accepts.

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

Plugin options

`context`

Type:

type context = string;

Default: compiler.context

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

`lintDirtyModulesOnly`

Type:

type lintDirtyModulesOnly = boolean;

Default: false

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

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.

`cacheLocation`

Type:

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.

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

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

`resourceQueryExclude`

Type:

type resourceQueryExclude = RegExp | RegExp[];

Default: []

Specify the resource query to exclude. 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" | 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:

Value	Effect
unset	Errors fail the build, warnings do not.
`"error"`	Everything fails the build, warnings included.
`"warning"`	Nothing fails the build; errors are reported as warnings.
`false`	Nothing is reported. An `outputReport` is still written.
`{ warnings: false }`	The errors alone, still failing the build.
`{ warnings: "error" }`	Warnings fail the build too, and errors keep failing it.
`{ errors: "warning" }`	Errors stop failing the build, and warnings stay warnings.

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

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

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

`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:

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.

`threads`

Type:

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.

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.

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, 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:

Was	Is
`quiet: true`, `emitWarning: false`	`reportAs: { warnings: false }`
`emitError: false`	`reportAs: { errors: false }`
`emitError: false` and `emitWarning: false`	`reportAs: false`
`failOnError: true`	the default
`failOnError: false`	`reportAs: "warning"`
`failOnWarning: true`	`reportAs: { warnings: "error" }`

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.

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:

Option	Now
`cache`	Unchanged, shared.
`cacheLocation`	Unchanged, shared. The default moved to `node_modules/.cache/diagnostics-webpack-plugin/.eslintcache`.
`configType`	Unchanged, in the `eslint` entry.
`context`	Unchanged, top level.
`emitError`	`reportAs`, see the table above.
`emitWarning`	`reportAs`, see the table above.
`eslintPath`	Unchanged, in the `eslint` entry.
`exclude`	Unchanged, shared.
`extensions`	Unchanged, shared. Still defaults to `js`.
`failOnError`	`reportAs`. It defaulted to on outside `development` mode; the default no longer depends on `mode`.
`failOnWarning`	`reportAs`, see the table above.
`files`	Unchanged, shared.
`fix`	Unchanged, shared.
`formatter`	Unchanged, shared.
`lintDirtyModulesOnly`	Unchanged, top level. It covers every check and cannot be set per check.
`outputReport`	Unchanged, shared. It is still written even when `reportAs` is `false`.
`quiet`	`reportAs: { warnings: false }`.
`resourceQueryExclude`	Unchanged, shared.

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:

Option	Now
`cache`	Unchanged, shared.
`cacheLocation`	Unchanged, shared. The default moved to `node_modules/.cache/diagnostics-webpack-plugin/.stylelintcache`.
`context`	Unchanged, top level.
`emitError`	`reportAs`, see the table above.
`emitWarning`	`reportAs`, see the table above.
`exclude`	Unchanged, shared.
`extensions`	Unchanged, shared. Still defaults to `css`, `scss` and `sass`.
`failOnError`	`reportAs`. It defaulted to on in every mode, and the default is still to fail on an error.
`failOnWarning`	`reportAs`, see the table above.
`files`	Unchanged, shared.
`formatter`	Unchanged, shared.
`lintDirtyModulesOnly`	Unchanged, top level. It covers every check and cannot be set per check.
`outputReport`	Unchanged, shared. It is still written even when `reportAs` is `false`.
`quiet`	`reportAs: { warnings: false }`.
`stylelintPath`	Unchanged, in the `stylelint` entry.
`threads`	Unchanged, in the `stylelint` entry.

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

Changelog

Contributing

We welcome all contributions!

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

CONTRIBUTING

License

MIT

Name		Name	Last commit message	Last commit date
.changeset		.changeset
.github/workflows		.github/workflows
.husky		.husky
src		src
test		test
types		types
.cspell.json		.cspell.json
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierignore		.prettierignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
babel.config.js		babel.config.js
commitlint.config.js		commitlint.config.js
eslint.config.mjs		eslint.config.mjs
lint-staged.config.js		lint-staged.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Uh oh!

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

diagnostics-webpack-plugin

Getting Started

Options

Plugin options

context

lintDirtyModulesOnly

Shared options

cache

cacheLocation

files

extensions

exclude

resourceQueryExclude

fix

formatter

Errors and warnings

reportAs

outputReport

ESLint

configType

eslintPath

Suppressions

Stylelint

stylelintPath

threads

Adding a check

Migrating

From eslint-webpack-plugin

From stylelint-webpack-plugin

Running both

Changelog

Contributing

License

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

`context`

`lintDirtyModulesOnly`

`cache`

`cacheLocation`

`files`

`extensions`

`exclude`

`resourceQueryExclude`

`fix`

`formatter`

`reportAs`

`outputReport`

`configType`

`eslintPath`

`stylelintPath`

`threads`

From `eslint-webpack-plugin`

From `stylelint-webpack-plugin`