Registry / testing / eslint-formatter-ratchet

eslint-formatter-ratchet

library3.0.0jsnpmunverified

ESLint formatter that enforces a ratcheting threshold on total lint issues to prevent new violations from creeping in. Current stable version: 3.0.0. It generates a baseline file (eslint-ratchet.json) from the initial lint run, then fails future runs if the total issue count exceeds that baseline, and updates the baseline when the count improves. Provides styled output and supports bypassing normal ESLint erroring via environment variable. Unlike other formatters, it focuses on total issue count rather than specific rules, making it useful for incremental codebase improvements. Requires Node >=22 and ESM.

testing devops

npm install eslint-formatter-ratchet

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ESLINT-FORMATTER-R

eslint-formatter-ratchet

testingjavascriptv3.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

eslint-formatter-ratchet

✓ import 'eslint-formatter-ratchet'

✗ const Ratchet = require('eslint-formatter-ratchet')

This package is an ESLint formatter, not a library. It is used via ESLint's -f flag. The import shown is only for TypeScript type augmentation if needed; the actual usage is via ESLint CLI.

Install the package and run ESLint with the ratchet formatter to set up a baseline that prevents new lint issues from being added.

// 1. Install npm install -D eslint-formatter-ratchet // 2. Run ESLint with the formatter to generate baseline // (Run this on the current codebase) eslint --format ratchet . // This creates: // - eslint-ratchet.json (baseline - commit this) // - eslint-ratchet-temp.json (temporary - gitignore this) // 3. On subsequent runs, if total issues exceed baseline, ESLint will exit with an error. // If issues are fewer, the baseline is updated automatically. // Example with npm script: // package.json: { "scripts": { "lint": "eslint --format ratchet .", "lint:fix": "eslint --fix && eslint --format ratchet ." } } // 4. (Optional) Use environment variable to bypass ESLint exit on violations: RATCHET_DEFAULT_EXIT_ZERO=true eslint --format ratchet .

Debug

Known issues

breakingRequires Node.js >=22 (as of v3.0.0). Older versions will not work.

fix

Update Node.js to version 22 or later. If you must use an older Node, install eslint-formatter-ratchet@2.x.

affects: >=3.0.0

gotchaThe formatter generates two files: eslint-ratchet.json (commit) and eslint-ratchet-temp.json (do not commit). Forgetting to gitignore eslint-ratchet-temp.json will cause dirty state.

fix

Add eslint-ratchet-temp.json to your .gitignore file.

affects: >=1.0.0

gotchaThe baseline file eslint-ratchet.json must exist for the formatter to run. If deleted, the first run will create a new baseline but not enforce until the next run.

fix

Ensure eslint-ratchet.json is committed to your repository. If lost, run eslint --format ratchet to regenerate it.

affects: >=1.0.0

deprecatedPrevious versions (1.x, 2.x) used CommonJS. Version 3.x is ESM-only, breaking require() usage.

fix

If you were using require('eslint-formatter-ratchet'), switch to import or use the CLI -f flag. Ensure your project is ESM or uses dynamic import.

affects: >=3.0.0

gotchaThe environment variable RATCHET_DEFAULT_EXIT_ZERO only affects ESLint exit code for rule violations, but the formatter will still throw if new issues are detected (i.e., the threshold exceeded). This can be confusing.

fix

Understand that RATCHET_DEFAULT_EXIT_ZERO=true suppresses ESLint's own error exit, but the formatter will still fail on new issues. Use only when you want ESLint to ignore violation exits but still enforce ratcheting.

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/eslint-formatter-ratchet/index.js from /path/to/project not supported. Instead change the require of index.js to a dynamic import() which is available in all CommonJS modules.

eslint-formatter-ratchet v3 is ESM-only, but your project or ESLint configuration uses require() to load it.

fix

Use ESLint's -f flag with the formatter name: eslint -f ratchet. If you need to load it programmatically, use dynamic import: const formatter = await import('eslint-formatter-ratchet');

Cannot find module 'eslint-formatter-ratchet'

The package is not installed, or ESLint is looking for it in the wrong location.

fix

Ensure eslint-formatter-ratchet is installed as a devDependency: npm install -D eslint-formatter-ratchet. Then run ESLint from the project root.

ENOENT: no such file or directory, open 'eslint-ratchet.json'

The baseline file does not exist and the formatter cannot create it because of permissions or missing directory.

fix

Run the formatter once to generate the baseline: eslint -f ratchet . This will create eslint-ratchet.json in the current working directory.

Parsing error: The keyword 'import' is reserved

Attempting to use import syntax in a CommonJS file that loads the formatter.

fix

Use the ESLint CLI -f flag instead of programmatic use. Or change your file to .mjs extension or add "type": "module" to package.json.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/Jmsa/eslint-formatter-ratchet ↗

packageeslint-formatter-ratchet ↗

homepagehttps://github.com/Jmsa/eslint-formatter-ratchet#readme ↗