stylelint-webpack-plugin

5.1.0 verified Sat Apr 25 auth: no javascript

A webpack plugin that runs Stylelint during the build process to lint CSS, SCSS, SASS, and other style files. Current stable version is 5.1.0, released February 2026. Supports webpack 5 only (for webpack 4, use the 2.x branch). Peer dependencies require Stylelint >=13 up to 17, and Node.js >=18.12.0 (v5 breaking change). Key differentiators: integrates linting directly into webpack compilation, supports caching (enabled by default since v4.1.1), autofixing, and custom formatters. Ships TypeScript types. Alternative to running Stylelint as a separate process or using other linting plugins like eslint-webpack-plugin for styles.

Common errors

error Error: Cannot find module 'stylelint' ↓

cause stylelint is not installed as a dependency.

fix

Run 'npm install stylelint --save-dev' in your project.

error Error: Cannot find module 'stylelint-webpack-plugin' ↓

cause Package not installed or not in node_modules.

fix

Run 'npm install stylelint-webpack-plugin --save-dev'.

error TypeError: StylelintPlugin is not a constructor ↓

cause Using import incorrectly (e.g., using named import instead of default).

fix

Use 'import StylelintPlugin from 'stylelint-webpack-plugin'' or for CommonJS: 'const StylelintPlugin = require('stylelint-webpack-plugin').default'.

Warnings

breaking Node.js 18 minimum required since v5.0.0 ↓

fix Upgrade Node.js to version 18 or later.

breaking Webpack 5 only since v3.0.0; webpack 4 users must use v2.x branch ↓

fix For webpack 4, use 'npm install stylelint-webpack-plugin@2'.

deprecated CommonJS require() style is deprecated in favor of ESM import ↓

fix Use 'import StylelintPlugin from 'stylelint-webpack-plugin'' instead of require().

gotcha Caching is enabled by default since v4.1.1; may cause stale results if cache not cleared ↓

fix Add 'cache: false' to plugin options or delete cache directory manually when changing Stylelint config.

deprecated Support for Stylelint 13 and 14 dropped in v5.1.0-? (check notes; v5.1.0 supports v13-v17) ↓

fix Upgrade to v5.1.0 if using Stylelint v16 or v17.

Install

npm install stylelint-webpack-plugin

yarn add stylelint-webpack-plugin

pnpm add stylelint-webpack-plugin

Imports

StylelintPlugin
wrong
```
const StylelintPlugin = require('stylelint-webpack-plugin')
```
correct
```
import StylelintPlugin from 'stylelint-webpack-plugin'
```
Package is ESM-first since v3.2.0; CommonJS require works in Node.js but may trigger ESM warnings. For webpack config, require is still commonly used.
StylelintPlugin (type)
```
import type { StylelintPlugin } from 'stylelint-webpack-plugin'
```
TypeScript type is exported for plugin options. Use import type for type-only usage.
StylelintWebpackPluginOptions
```
import type { StylelintWebpackPluginOptions } from 'stylelint-webpack-plugin'
```
Available since v5.0.0; defines the options object type.

Quickstart

Basic webpack config integrating StylelintPlugin with common options: files glob, caching enabled, and custom config file.

// webpack.config.js
import StylelintPlugin from 'stylelint-webpack-plugin';

export default {
  // ... other webpack config
  plugins: [
    new StylelintPlugin({
      files: 'src/**/*.{css,scss,sass}',
      fix: false,
      cache: true,
      cacheLocation: 'node_modules/.cache/stylelint-webpack-plugin',
      context: __dirname,
      extensions: ['css', 'scss', 'sass'],
      exclude: ['node_modules'],
      lintDirtyModulesOnly: false,
      formatter: 'string',
      configFile: '.stylelintrc.json',
    }),
  ],
};