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 > 16 and node >= 18.12.0.

# 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", "github", "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', save: 'report.json' },
        { formatter: myStylelintFormatter, save: '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", "github", "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)
  save: 'stylelint-report.txt'
}