stylelint-plugin-file-progress

A little clarity for every lint run

• Native Stylelint integration. One observational rule that leaves CSS, fixes, and diagnostics intact.
• Output that fits your workflow. File, compact, and summary modes, with presets for CI and interactive terminals.
• Useful process summaries. Observed file counts, elapsed time, throughput, and exit-code appearance.
• Your terminal, your preferences. Progress updates in place, with colored paths, spinner frames, marks, messages, streams, and display thresholds.
• Typed and portable. ESM and CommonJS exports, TypeScript declarations, and seven configuration subpaths.

Explore every preset and option demo. These reproducible recordings use the actual display controller; their timings illustrate process metrics.

Contents

• Quick start
• Choose a preset
• Customize the display
• Rule reference
• Compatibility and metrics
• Explore the project
• Contributing and attribution

Quick start

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

Add the preset after your existing shared configs in stylelint.config.mjs:

export default {
 extends: [
  // Keep your existing shared configs above this entry.
  "stylelint-plugin-file-progress/configs/recommended",
 ],
};

Then run Stylelint as usual:

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

The preset supplies progress output; keep your existing Stylelint rules or shared config for CSS diagnostics. See the setup guide for CommonJS and formatter examples.

Choose a preset

Every preset enables file-progress/activate. Use the exact subpath stylelint-plugin-file-progress/configs/<preset> in your extends array.

| Preset | Best for | Behavior | | --------------------------------------------------------------------------------------------------------------------------- | --------------------------- | -------------------------------------------------------------------- | | 🟢 recommended | Follow each stylesheet | Show each file using the default display options. | | 🔵 recommended-ci | Keep CI logs quiet | Hide all plugin output when CI is exactly true. | | 🟣 recommended-ci-detailed | Keep a summary in CI | Hide live output in CI while retaining the detailed process summary. | | 🟡 recommended-compact | Show activity without paths | Announce generic activity once, without showing filenames. | | 🟠 recommended-detailed | See process-wide metrics | Show filenames and the detailed process summary. | | 🩷 recommended-summary-only | Read the final summary | Show only the final process summary. | | 🟦 recommended-tty | Respect redirected output | Show output only when stderr is an interactive terminal. |

Compare configurations and watch their demos. The CI presets check whether CI is exactly true; outside CI they show ordinary progress.

Customize the display

Override the rule's secondary options after extending a preset:

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

Set "file-progress/activate": null to disable progress, including when another shared config enables it.

Rule reference

| Rule | Purpose | | ------------------------------------------------ | ---------------------------------------------------- | | file-progress/activate | Observe files without changing CSS or lint findings. |

The complete option reference covers display modes, paths, streams, marks, spinner frames, throttling, and summary settings. The API reference documents the public types and exports.

Compatibility and metrics

| Surface | Support | | ----------------------- | --------------------------------------------------------------------------- | | Node.js | 22 and later. | | Stylelint | ^16.0.0 or ^17.14.0. | | Module formats | ESM and CommonJS, with TypeScript declarations. | | CommonJS + Stylelint 17 | Node 22.12+ for synchronous ESM loading. | | Default stream | stderr; stdout remains intact. | | Custom syntaxes | One notice per processing result, including inputs with multiple CSS roots. |

A filename event means the stylesheet reached the progress rule. Ignored inputs, unchanged cached inputs, and parsing failures before rule execution are not observed. Counts describe observed file-processing events, including repeated lint calls.

Summaries span the process lifetime. They do not provide exact total inputs, percentages, ETA, problem counts, or per-file completion times. The success/failure appearance follows the process exit code.

Stylelint's normal CLI report also uses stderr. For an intact machine-readable report:

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

Read compatibility and metric boundaries or troubleshooting for cache behavior, watch processes, terminal output, and missing summaries.

Explore the project

| Resource | Purpose | | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | Documentation | Setup, presets, demos, and reference guides. | | Stylelint Inspector | Explore the repository's resolved Stylelint configuration. | | ESLint Inspector | Explore the repository's TypeScript and tooling lint setup. | | Releases · Changelog | Published artifacts and full change history. | | Issues · Support | Bug reports, questions, and feedback. | | ESLint File Progress | The ESLint counterpart and inspiration. | | ESLint Typefest | TypeScript-focused rules for type-fest and ts-extras. | | Shared Stylelint config | The shared configuration used by this project. |

Contributing and attribution

See CONTRIBUTING.md for development, documentation generation, and the full verification gate. Report security concerns using SECURITY.md.

Created by Nick2bad4u. Licensed under MIT. See NOTICE for attribution to the ESLint progress project.