Linting CSS

Kea - High level abstraction between React and Redux - Interview with Marius Andra

As discussed earlier in the Linting JavaScript chapter, linting is a technique that allows to avoid certain categories of mistakes. Automation is good, as it can save effort. In addition to JavaScript, it's possible to lint CSS.

Stylelint is a tool that allows linting. It can be used with webpack through postcss-loader.

Connecting Stylelint with package.json#

To get started, install Stylelint as a development dependency:

npm install stylelint --save-dev

To connect Stylelint with npm and make it find the CSS files, adjust as follows:


"scripts": {
"lint:style": "stylelint app/**/*.css",
... },

To have something to test with, there should be a dummy rule:


  "rules": {
    "color-hex-case": "lower"

If you break the rule at app/main.css and run npm run lint:style, you should see a message:

 2:15  Expected "#FFF" to be "#fff"   color-hex-case

To get less verbose output on error, use either npm run lint:style --silent or npm run lint:style -s.

The same rules can be connected with webpack.

Connecting Stylelint with Webpack#

To get started, install postcss-loader unless you have it set up already:

npm install postcss-loader --save-dev

Next, to integrate with configuration, set up a part first:

exports.lintCSS = ({ include, exclude }) => ({
  module: {
    rules: [
        test: /\.css$/,
        enforce: 'pre',

        loader: 'postcss-loader',
        options: {
          plugins: () => ([

Then add it to the common configuration:


const commonConfig = merge([
parts.lintCSS({ include: }),

If you define a CSS rule, such as background-color: #EFEFEF; at main.css now, you should see a warning at your terminal when you run the build (npm start or npm run build):

WARNING in ./~/css-loader!./~/postcss-loader!./app/main.css
stylelint: /webpack-demo/app/main.css:2:21: Expected "#EFEFEF" to be "#efefef" (color-hex-case)
 @ ./app/main.css 4:14-117
 @ ./app/index.js

See the Stylelint documentation for a full list of rules. npm lists possible rulesets you can enable through configuration.

stylelint-scss provides a collection of SCSS specific linting rules.
The enforce idea is discussed in detail in the Loader Definitions chapter.
If you get Module build failed: Error: No configuration provided for ... kind of error, check your .stylelintrc.


stylelint-webpack-plugin allows you to reach the same result. Its greatest advantage over the setup above is that it follows possible @import statements you have in your styling.

stylelint-bare-webpack-plugin is a variant of stylelint-webpack-plugin that allows you to control the version of Stylelint you are using.


CSSLint is another option to Stylelint. It can be used through csslint-loader and follows a normal loader setup.


After these changes, there is style linting in place. Now you can catch CSS-related problems.

To recap:

  • It's possible to lint CSS through Stylelint.
  • Linting CSS allows you to capture common CSS-related problems and disallow problematic patterns.
  • Stylelint can be treated as a PostCSS plugin, but it can also be used through stylelint-webpack-plugin.
  • CSSLint is an option to Stylelint. It's possible the projects merge, though.
Previous chapterEliminating Unused CSS
Next chapterLoading Assets

This book is available through Leanpub (digital), Amazon (paperback), and Kindle (digital). By purchasing the book you support the development of further content. A part of profit (~30%) goes to Tobias Koppers, the author of webpack.

Need help?