Live per-file progress output from the `recommended-detailed` preset.
- This page shows the default recommended preset options:
- [✅ `recommended` preset page](./docs/rules/presets/recommended.md)
- But there are a lot of ways to customize the output, and this page has a demo of every single rule option in action:
- [⭐ `activate` rule page](./docs/rules/activate.md#rule-options)
## Installation
```bash
npm install --save-dev eslint-plugin-file-progress-2
```
## Quick start
Use the default preset when you want full per-file progress during local CLI runs:
```ts
// eslint.config.mjs
import progress from "eslint-plugin-file-progress-2";
export default [progress.configs.recommended];
```
Need the `recommended` baseline with small behavior tweaks (for example
`fileNameOnNewLine`)? Keep the preset and add a targeted override after it:
```ts
// eslint.config.mjs
import progress from "eslint-plugin-file-progress-2";
export default [
progress.configs.recommended,
{
rules: {
"file-progress/activate": [
"warn",
{
fileNameOnNewLine: true,
throttleMs: 120,
},
],
},
},
];
```
## Configure a rule directly
Modern ESLint usage should configure progress behavior as rule options:
```ts
// eslint.config.mjs
import progress from "eslint-plugin-file-progress-2";
export default [
{
plugins: {
"file-progress": progress,
},
rules: {
"file-progress/activate": [
"warn",
{
outputStream: "stderr",
throttleMs: 100,
ttyOnly: true,
},
],
},
},
];
```
### Rule Options
- For the full option interface, defaults, example usage GIFs, and option-by-option behavior explanation:
- [⭐ `activate` Rule Page](./docs/rules/activate.md#rule-options)
## Presets
The plugin now ships with these Flat Config-ready presets:
- `recommended`: full per-file progress using default options
- `recommended-ci`: hides progress when `CI === "true"`
- `recommended-detailed`: enables the detailed completion summary
- `recommended-compact`: enables the compact live mode
- `recommended-summary-only`: prints only the final summary
- `recommended-tty`: enables `ttyOnly: true`
- `recommended-ci-detailed`: hides live output in CI but still prints the detailed summary there
Use any preset exactly the same way:
```ts
// eslint.config.mjs
import progress from "eslint-plugin-file-progress-2";
export default [progress.configs["recommended-compact"]];
```
## Migration note
`file-progress/compact` and `file-progress/summary-only` were removed from the
public rule surface.
If you previously configured either rule directly, migrate to
`file-progress/activate` with `mode` instead:
```ts
rules: {
"file-progress/activate": ["warn", { mode: "compact" }],
}
```
```ts
rules: {
"file-progress/activate": ["warn", { mode: "summary-only" }],
}
```
The preset names `recommended-compact` and `recommended-summary-only` still
exist. They now enable `file-progress/activate` with the matching `mode`.
This is a breaking API change. If you publish it, it should ship in a major
release rather than a minor release.
## Deprecated configuration fallback
`settings.progress` still works as a backwards-compatible fallback, but it is now deprecated.
Prefer this:
```ts
rules: {
"file-progress/activate": ["warn", { pathFormat: "basename" }],
}
```
Instead of this:
```ts
settings: {
progress: {
hideDirectoryNames: true,
},
}
```
If both are present, rule options win.
## Rules
Generated from the plugin rule metadata and preset registry.
| Rule | Description | Included in presets |
| ---------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`file-progress/activate`](./docs/rules/activate.md) | Display live per-file lint progress in CLI output. | [`recommended`](./docs/rules/presets/recommended.md), [`recommended-ci`](./docs/rules/presets/recommended-ci.md), [`recommended-ci-detailed`](./docs/rules/presets/recommended-ci-detailed.md), [`recommended-compact`](./docs/rules/presets/recommended-compact.md), [`recommended-detailed`](./docs/rules/presets/recommended-detailed.md), [`recommended-summary-only`](./docs/rules/presets/recommended-summary-only.md), [`recommended-tty`](./docs/rules/presets/recommended-tty.md) |
## CLI-only usage
If you do not want editor integrations to see these runtime rules, keep the plugin out of your shared config and enable it only from the CLI:
```bash
npx eslint . --plugin file-progress --rule 'file-progress/activate: warn'
```
Or expose that through a package script:
```json
{
"scripts": {
"lint": "eslint .",
"lint:progress": "eslint . --plugin file-progress --rule \"file-progress/activate: warn\""
}
}
```
## Contributing
- Contributor and release documentation is available in [DEVELOPMENT.md](./DEVELOPMENT.md).
- The Docusaurus/TypeDoc site source lives under [`docs/docusaurus`](./docs/docusaurus).
- Rule docs live under [`docs/rules`](./docs/rules).
