Migrating Between ESLint Versions

Migration strategy

ESLint 9 made flat config the default and v10 removes the old format. Migrate with npx @eslint/migrate-config .eslintrc.json, test locally, then roll out gradually, using --max-warnings for a transition period.

Safe upgrade process

Steps for upgrading ESLint without breaking the team.

# 1. Upgrade
npm install --save-dev eslint@latest @eslint/js

# 2. Convert the old config
npx @eslint/migrate-config .eslintrc.json   # creates eslint.config.mjs

# 3. Test locally and fix what you can
npm run lint
npx eslint . --fix

# 4. Transition period: cap warnings and reduce over time
npx eslint . --max-warnings 50

# 5. Commit and open a PR
git commit -am "chore: migrate to ESLint 9 flat config"

Output:

ESLint upgraded safely

Read release notes

ESLint releases often include breaking changes and new rules. Read the release notes to understand what changed and plan your migration.

Quick check

Quick check: How should you upgrade ESLint in a team?

• Test locally, fix issues gradually, use --max-warnings during transition.
• Upgrade immediately on all machines.
• Never upgrade, stay on old versions.
• Delete eslint.config.js