Skip to main content

Getting started

Add live progress to your existing Stylelint workflow with one preset. The plugin observes files without changing CSS, fixes, or diagnostics.

Install​

npm install --save-dev stylelint stylelint-plugin-file-progress

The plugin supports Node.js 22+ and Stylelint ^16.0.0 || ^17.14.0. See module compatibility for the CommonJS requirements with Stylelint 17.

Enable a preset​

Add the preset to stylelint.config.mjs:

export default {
 extends: [
  // Keep your existing shared configs here, before the progress preset.
  "stylelint-plugin-file-progress/configs/recommended",
 ],
};

Then run Stylelint with your usual inputs:

npx stylelint "src/**/*.css"

You will see a filename when each stylesheet reaches the progress rule, followed by a summary at process shutdown. The progress preset supplies no CSS lint rules of its own; keep the shared config or rules you already use.

Choose your level of detail

Use recommended-detailed for process metrics, recommended-ci-detailed for a summary without live output when CI=true, or compare all seven presets.

CommonJS​

The same preset subpath works in stylelint.config.cjs:

module.exports = {
 extends: ["stylelint-plugin-file-progress/configs/recommended"],
};

With Stylelint 17, CommonJS consumers need Node 22.12+ for synchronous ESM loading. Node 22.0.0 is supported with Stylelint 16 in both module formats.

Customize the display​

Override the rule after extending a preset. These are Stylelint secondary options:

export default {
 extends: ["stylelint-plugin-file-progress/configs/recommended"],
 rules: {
  "file-progress/activate": [
   true,
   {
    pathFormat: "basename",
    spinnerStyle: "line",
    detailedSuccess: true,
   },
  ],
 },
};

Explore all options and defaults or watch the option demos before choosing your display.

Keep machine-readable reports intact​

Progress uses stderr by default. Stylelint's CLI diagnostic report also uses stderr, so write a JSON report to a separate file when another tool needs to parse it:

npx stylelint "src/**/*.css" --formatter json --output-file report.json

The default stream leaves stdout intact, including CSS produced when fixing stdin. Selecting outputStream: "stdout" mixes progress into that stream. Read output behavior for details.

Disable progress​

Set the rule to null in an override:

export default {
 extends: ["stylelint-plugin-file-progress/configs/recommended"],
 rules: {
  "file-progress/activate": null,
 },
};

This also works when the rule comes from another shared config. For watch processes and editors, summaries span the process lifetime.

Next steps​