Skip to main content

PostCSS plugin

As with any other PostCSS plugin, you can use Stylelint's PostCSS plugin either with a PostCSS runner or with the PostCSS JS API directly.

However, if a dedicated Stylelint task runner plugin is available (e.g. gulp-stylelint) we recommend you use that rather than this plugin, as they provide better reporting.

Options#

The PostCSS plugin uses the standard options, except the customSyntax option. Instead, the syntax must be set within the PostCSS options as there can only be one parser/syntax in a pipeline.

Usage examples#

We recommend you lint your CSS before applying any transformations. You can do this by either:

  • creating a separate lint task that is independent of your build one.
  • using the plugins option of postcss-import or postcss-easy-import to lint your files before any transformations.
  • placing Stylelint at the beginning of your plugin pipeline.

You'll also need to use a reporter. The Stylelint plugin registers warnings via PostCSS. Therefore, you'll want to use it with a PostCSS runner that prints warnings or another PostCSS plugin whose purpose is to format and print warnings (e.g. postcss-reporter).

Example A#

A separate lint task that uses the plugin via the PostCSS JS API to lint Less using postcss-less.

const fs = require("fs");const less = require("postcss-less");const postcss = require("postcss");
// Code to be processedconst code = fs.readFileSync("input.less", "utf8");
postcss([  require("stylelint")({    /* your options */  }),  require("postcss-reporter")({ clearReportedMessages: true })])  .process(code, {    from: "input.less",    syntax: less  })  .then(() => {})  .catch((err) => console.error(err.stack));

The same pattern can be used to lint Less, SCSS or SugarSS syntax.

Example B#

A combined lint and build task where the plugin is used via the PostCSS JS API, but within postcss-import (using the its plugins option) so that the source files are linted before any transformations.

const fs = require("fs");const postcss = require("postcss");const stylelint = require("stylelint");
// CSS to be processedconst css = fs.readFileSync("lib/app.css", "utf8");
postcss([  require("postcss-import")({    plugins: [      require("stylelint")({        /* your options */      })    ]  }),  require("postcss-preset-env"),  require("postcss-reporter")({ clearReportedMessages: true })])  .process(css, {    from: "lib/app.css",    to: "app.css"  })  .then((result) => {    fs.writeFileSync("app.css", result.css);
    if (result.map) {      fs.writeFileSync("app.css.map", result.map);    }  })  .catch((err) => console.error(err.stack));