Gulp Stylelint

This package is pure ESM. Please read this.

A Gulp plugin that runs stylelint results through a list of reporters with ESM support.

Installation

[!NOTE] REQUIREMENTS: Supports gulp v4 and v5, stylelint > 17 and node > 22.22.2. It might work with stylelint 16 too, but without the github formatter

# YARN
yarn add stylelint gulp-stylelint-esm -D
# NPM
npm install stylelint gulp-stylelint-esm --save-dev

Quick start

Once you have configured stylelint, start with the following code. You will find additional configuration options below.

import { src } from 'gulp';
import gStylelintEsm from 'gulp-stylelint-esm';

function lintCssTask() {
  return src('src/**/*.css')
    .pipe(gStylelintEsm());
}

Formatters

Below is the list of currently available stylelint formatters. Some of them are bundled with stylelint by default and exposed on gStylelintEsm.formatters object. Others need to be installed. You can write a custom formatter to tailor the reporting to your needs.

Formatters bundled with stylelint: "compact", "json", "string", "tap", "unix", "verbose".

The plugin comes with a built-in formatter called "stylish", which is set as the default.

Options

gulp-stylelint-esm supports all stylelint and Node.js API options except:

• files, code will be provided by gulp instead
• formatter, formatters are defined in the reporters option
• cache, gulp caching should be used instead

and accepts a custom set of options listed below:

import { src } from 'gulp';
import gStylelintEsm from 'gulp-stylelint-esm';
import { myStylelintFormatter } from 'my-stylelint-formatter';

function lintCssTask() {
  return src('src/**/*.css')
    .pipe(gStylelintEsm({
      failAfterError: true, // true (default) | false
      fix: false,           // false (default) | true
      reporters: [
        { formatter: 'stylish', console: true }, // default
        { formatter: 'json', log: 'report.json' },
        { formatter: myStylelintFormatter, log: 'my-custom-report.txt' }
      ],
      debug: false          // false (default) | true
    }));
}

failAfterError

When set to true, the process will end with non-zero error code if any error-level warnings were raised. Files are pushed back to the their pipes only if there are no errors. Defaults to true.

fix

The fix: true (autofix) option instructs stylelint to try to fix as many issues as possible. Defaults to false.

NOTE:

• fixed files will automatically overwrite the original files; proceed with caution.
• the fixes are applied to the gulp stream only if there are no errors, to allow usage of other plugins.
• not all stylelint rules can be automatically fixed, so it's advisable to manually resolve errors.

import { src, dest } from 'gulp';
import gStylelintEsm from 'gulp-stylelint-esm';

function fixCssTask() {
  return src('src/**/*.css')
    .pipe(gStylelintEsm({
      fix: true
    }))
    .pipe(dest('src'));
}

reporters

List of reporter configuration objects (see below). Defaults to:

reporters: [
  { formatter: 'stylish', console: true }
]

{
  // stylelint results formatter (required):
  // - pass a built-in formatter
  // - pass a function for imported, custom or exposed formatters
  // - pass a string for formatters bundled with stylelint
  //   "stylish (default)", "string", "compact", "json", "tap", "unix", "verbose"
  formatter: stylish,

  // log the formatted result to console (optional):
  console: true,

  // save the formatted result to a file (optional):
  // - provide a path to the logs directory
  // save: 'logs/stylelint-report.txt'
  // - or save the report to root (default)
  log: 'stylelint-report.txt'
}

debug

When set to true, the error handler will print an error stack trace. Defaults to false.

License

See the LICENSE file for license rights and limitations (MIT).