@rmnddesign/eslint-baseline

Adopt strict ESLint rules without fixing everything at once.

The Problem

You want to enable stricter ESLint rules, but your codebase has 500+ existing errors. You have two bad options:

1. Fix everything first - Takes weeks, blocks other work
2. Don't enable the rules - Tech debt keeps growing

The Solution

Baseline the existing errors. New code must follow the rules, old code gets a pass (for now).

# Snapshot current errors
npx @rmnddesign/eslint-baseline init

# In CI - fail only on NEW errors
npx @rmnddesign/eslint-baseline check

# After fixing some errors, update the baseline
npx @rmnddesign/eslint-baseline update

Installation

npm install -D @rmnddesign/eslint-baseline

How It Works

1. init - Runs ESLint, saves all current errors to .eslint-baseline.json
2. check - Runs ESLint, compares against baseline, fails only if there are NEW errors
3. update - Updates the baseline with current errors (after you've fixed some)

The baseline file should be committed to git so your whole team shares it.

Commands

eslint-baseline init

Generate a baseline from your current ESLint errors.

npx eslint-baseline init

Output:

Running ESLint...
Baseline created: .eslint-baseline.json
Baselined 127 errors across 45 unique issues

Add this file to git so your team shares the same baseline.

eslint-baseline check

Check for new errors. Exits with code 1 if new errors are found.

npx eslint-baseline check

If no new errors:

✓ No new ESLint errors!
  12 baselined error(s) have been fixed.
  Run 'eslint-baseline update' to update the baseline.

If new errors found:

✗ Found 2 new ESLint error(s):

src/utils.ts
  no-unused-vars: 'helper' is defined but never used
  no-console: Unexpected console statement

Fix these errors or run 'eslint-baseline update' to baseline them.

eslint-baseline update

Update the baseline with current errors. Use this after fixing errors, or to baseline new errors.

npx eslint-baseline update

Output:

Running ESLint...
Baseline updated: 12 error(s) removed!
Total baselined errors: 115

eslint-baseline stats

Show statistics about your baseline.

npx eslint-baseline stats

Output:

Baseline Statistics
───────────────────
Generated: 3/13/2026, 2:30:00 PM
Total errors: 127
Unique issues: 45

Errors by rule:
    42  @typescript-eslint/no-explicit-any
    28  no-console
    15  @typescript-eslint/no-unused-vars
    12  prefer-const
     8  no-empty
  ... and 5 more rules

CI Integration

GitHub Actions

name: Lint

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npx eslint-baseline check

Pre-commit Hook

// package.json
{
  "scripts": {
    "lint": "eslint-baseline check"
  }
}

Workflow

Initial Setup

# 1. Enable the strict rules you want in your ESLint config

# 2. Generate baseline (this "grandfathers" existing errors)
npx eslint-baseline init

# 3. Commit the baseline
git add .eslint-baseline.json
git commit -m "Add ESLint baseline"

Daily Development

# CI runs this - fails if you introduce NEW errors
npx eslint-baseline check

Fixing Errors Over Time

# Fix some errors in your code...

# Update baseline to reflect the fixes
npx eslint-baseline update

# Commit the updated baseline
git commit -am "Fix 12 ESLint errors"

Baseline Format

The .eslint-baseline.json file looks like this:

{
  "version": 1,
  "generated": "2026-03-13T14:30:00.000Z",
  "totalErrors": 127,
  "errors": [
    {
      "file": "src/utils.ts",
      "rule": "no-console",
      "message": "Unexpected console statement",
      "count": 5
    }
  ]
}

Errors are identified by file + rule + message. Line numbers are ignored since they shift as code changes.

FAQ

Does this work with any ESLint config?

Yes. We just run eslint . --format json and parse the output. Your rules, plugins, and config are all respected.

What if I want to baseline only specific rules?

Currently we baseline all errors. You could manually edit .eslint-baseline.json to remove entries for rules you want enforced immediately.

Can I use this with TypeScript ESLint?

Yes. Any ESLint plugin works - we just read the JSON output.

What about warnings?

Currently we only track errors (severity 2), not warnings. Warnings don't fail CI anyway.

License

MIT