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 processed
const 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 processed
const 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));