Add ESLint to an Existing Project Without 500 Errors

You add ESLint to a project that's three years old, run it, and get 500 errors. Nobody's going to fix 500 errors this week, so either the linter gets turned off, or it stays on and everyone learns to ignore it. Neither helps. The way through is to accept the existing problems as a baseline and make the linter fail only on new ones.

Step 1: install with the recommended rules only

npm install --save-dev eslint @eslint/js globals

Create eslint.config.js:

import js from "@eslint/js";
import globals from "globals";

export default [
  js.configs.recommended,
  {
    files: ["**/*.js"],
    languageOptions: {
      globals: { ...globals.node },
    },
  },
];

Start with recommended and nothing else. It's mostly real bugs. Style rules come later, if ever. Use globals.browser instead of globals.node for front-end code. (If your package.json doesn't have "type": "module", name the file eslint.config.mjs.)

Step 2: let it fix what it can, in its own commit

npx eslint --fix .
git add -A
git commit -m "ESLint autofix"

Autofixes are mechanical. Keeping them in their own commit means a reviewer can skim it, and if something breaks, it's easy to find.

Step 3: look at what's left

Run npx eslint . and read a few findings before you decide anything. On an old file, you'll see things like this (ESLint 10.12, file path line left out):

   9:9   error  'status' is constant                                             no-const-assign
   9:9   error  Expected a conditional expression and instead saw an assignment  no-cond-assign
   9:9   error  Unexpected constant condition                                    no-constant-condition
   9:9   error  'status' is assigned a value but never used                      no-unused-vars
   9:26  error  'total' is assigned a value but never used                       no-unused-vars
  11:10  error  'totl' is not defined                                            no-undef

That was an if (status = "paid") and a typo in a return. Both are real bugs that would crash when that code runs. Fix the ones like this now, even if you baseline everything else. Six messages, two bugs, maybe five minutes.

Step 4: baseline the rest

npx eslint --suppress-all .

This writes eslint-suppressions.json, a count of existing problems per file and rule. From now on, npx eslint . passes on those, and still reports anything new. Commit the file.

A new file with problems still fails:

$ echo "export const z = (a) => b;" > src/new.js
$ npx eslint .
  1:19  error  'a' is defined but never used  no-unused-vars
  1:25  error  'b' is not defined             no-undef

✖ 2 problems (2 errors, 0 warnings)

Old problems are tolerated. New ones block. The code can only get better.

Step 5: put it in CI

"scripts": {
  "lint": "eslint ."
}

Run npm run lint in CI before the tests. Add the ESLint extension to your editor, so people see problems while typing instead of after pushing.

Step 6: shrink the baseline

When you're working in a file anyway, fix its suppressed problems. Then run:

npx eslint --prune-suppressions .

It removes entries that are already fixed, so they can't come back. Over a few months, the file gets shorter.

What would happen to the baseline approach if someone ran npx eslint --suppress-all . again every time CI failed?