stylelint-webpack-plugin

What is stylelint-webpack-plugin?

The stylelint-webpack-plugin is a plugin for Webpack that integrates Stylelint, a popular CSS linter, into the Webpack build process. It helps developers enforce consistent coding styles and catch errors in CSS, SCSS, and other style files.

What are stylelint-webpack-plugin's main functionalities?

Linting CSS files

This feature allows you to lint all CSS files in your project. The plugin will check for style errors and enforce coding standards as defined in your Stylelint configuration.

const StylelintPlugin = require('stylelint-webpack-plugin');

module.exports = {
  plugins: [
    new StylelintPlugin({
      files: '**/*.css',
    }),
  ],
};

Linting SCSS files

This feature allows you to lint all SCSS files in your project. The plugin will check for style errors and enforce coding standards as defined in your Stylelint configuration.

const StylelintPlugin = require('stylelint-webpack-plugin');

module.exports = {
  plugins: [
    new StylelintPlugin({
      files: '**/*.scss',
    }),
  ],
};

Custom Stylelint configuration

This feature allows you to specify a custom Stylelint configuration file. The plugin will use the rules defined in the specified configuration file to lint your style files.

const StylelintPlugin = require('stylelint-webpack-plugin');

module.exports = {
  plugins: [
    new StylelintPlugin({
      configFile: '.stylelintrc.json',
    }),
  ],
};

Fixing errors automatically

This feature allows the plugin to automatically fix certain style errors. It can save time by correcting issues that can be automatically resolved according to the Stylelint rules.

const StylelintPlugin = require('stylelint-webpack-plugin');

module.exports = {
  plugins: [
    new StylelintPlugin({
      fix: true,
    }),
  ],
};

Other packages similar to stylelint-webpack-plugin

eslint-webpack-plugin

The eslint-webpack-plugin integrates ESLint into the Webpack build process. While ESLint is primarily used for JavaScript and TypeScript linting, it can also be configured to lint styles in JavaScript files. However, it is not as specialized for CSS and SCSS as stylelint-webpack-plugin.

postcss-loader

The postcss-loader is a Webpack loader that processes CSS with PostCSS. While it is not a linter, it can be used with PostCSS plugins like stylelint to achieve similar functionality. It offers more flexibility but requires additional configuration.

stylelint

Stylelint is the core linter that stylelint-webpack-plugin integrates with. It can be used directly in a project without Webpack, often through a task runner like Gulp or Grunt, or via command line. Using it directly offers more control but requires manual integration into the build process.

README

Stylelint Plugin for Webpack v[1, 3]

Why you might want to use this plugin instead of stylelint-loader

stylelint-loader lints the files you require or the ones you define as an entry in your webpack config. But @imports in those files are not followed, so just the main file (for each require/entry) is linted.

Instead, with stylelint-webpack-plugin you just define file globs, like stylelint does by default. So you get all your files linted.

Install

npm install --save-dev stylelint stylelint-webpack-plugin
# OR
yarn add --dev stylelint stylelint-webpack-plugin

Usage

In your webpack configuration

var StyleLintPlugin = require('stylelint-webpack-plugin');

module.exports = {
  // ...
  plugins: [
    new StyleLintPlugin(options),
  ],
  // ...
}

Options

See stylelint options for the complete list of options. This object is passed straight to the stylelint.lint function and has the following defaults:

• configFile: You can change the config file location. Default: (undefined), handled by stylelint's cosmiconfig module.
• context: String indicating the root of your SCSS files. Default: inherits from webpack config.
• emitErrors: Pipe stylelint 'error' severity messages to the error message handler in webpack's current instance. Note when this property is disabled (false) all stylelint messages are piped to webpack's warning message handler. Default: true
• failOnError: Throw a fatal error in the global build process (e.g. kill your entire build process on any stylelint 'error' severity message). Default: false
• files: Change the glob pattern for finding files. Must be relative to options.context. Default: ['**/*.s?(a|c)ss']
• formatter: Use a custom formatter to print errors to the console. Default: require('stylelint').formatters.string
• lintDirtyModulesOnly: Lint only changed files, skip lint on start. Default: false
• syntax: e.g. use 'scss' to lint .scss files. Default: undefined
• quiet: Prints stylelint output directly to the console if negated. Default: true.

Errors

The plugin will dump full reporting of errors. Set failOnError to true if you want webpack build process breaking with any stylelint error. You can use the quiet option to not print stylelint output to the console.

Acknowledgement

This project is basically a modified version of sasslint-webpack-plugin. It changed considerably since stylelint is async, and its Node API changes compared with sasslint.

Thanks to Javier (@vieron) for originally publishing this plugin, and passing the torch to our growing list of contributors! :smile:

License