# Migrate an ESLint 8 Project from .eslintrc to Flat Config

Yes. The agent runs the official migration, restores what it drops, and separates new ESLint 9 reports from problems the old setup was never checking.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-eslint-flat-config/eslint/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

Flat config replaces a cascade of files with one array, so the agent first maps the cascade. In a package like forwardemail/supertest there are two files. `.eslintrc` at the root extends `airbnb-base/legacy`, sets the `node` and `mocha` environments and `ecmaVersion: 6`, and overrides seven rules, each with a comment giving the reason. `test/.eslintrc` relaxes three rules for the tests: it turns off `no-unused-expressions` for the assertion style, and loosens `no-unused-vars` and `no-param-reassign`. The `lint` script in `package.json` is `eslint lib/**/*.js test/**/*.js index.js`, and `pretest` runs it, so a lint error blocks `npm test`. Before touching anything the agent saves the resolved rules for one library file and one test file with `eslint --print-config`. That snapshot is what the migration is checked against.

It picks the target version from the facts. When this page was written ESLint 10 required Node `^20.19.0 || ^22.13.0 || >=24`, and `eslint-plugin-import`, which the Airbnb config depends on, accepted ESLint up to 9. The workflow in `.github/workflows/ci.yml` still tests Node 18. ESLint 9 is the newest release that every job in that matrix can run, so that is the target. `eslint-config-airbnb-base` 15 declares a peer range that ends at ESLint 8, and npm installs ESLint 9 beside it with an `ERESOLVE overriding peer dependency` warning. Then the agent runs `npx @eslint/migrate-config .eslintrc`. The tool writes `eslint.config.mjs`, wraps the Airbnb config in `FlatCompat`, maps the two environments to `globals`, sets `sourceType: "commonjs"`, and asks for three more packages.

The first lint on the generated file reports 46 problems where there were none, 43 errors and 3 warnings, and the agent sorts them by cause before fixing any. Forty errors come from one omission: the tool converts the file it is given and nothing else, so the three overrides in `test/.eslintrc` are gone. Adding a block with `files: ["test/**/*.js"]` removes them. Three errors are ESLint 9 itself: `no-unused-vars` now checks caught errors by default, and the linted files have an unused binding in three `catch` clauses, such as `catch (_)`. The agent proves the cause by running ESLint 9 on the old config format, which reports the same lines, and restores the old behaviour with `caughtErrors: "none"`. The three warnings are `eslint-disable` comments that suppress nothing, which ESLint 9 reports by default.

The last finding is about what was never checked. The `lint` script's globs are unquoted, so the shell expands `lib/**/*.js` before ESLint sees it, and without globstar that matches only `lib/cookies/`. `lib/agent.js` and `lib/test.js` have never been linted. Checked directly under the old setup, `lib/test.js` has three errors; under the new one the two files also hold three more unused catch bindings and two more stale directives. The agent keeps the script's file set as it is, so the migration stays a migration, and reports the gap with both counts. It ends by comparing `--print-config` again: 252 rules before and after, with the same severity on each.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Migrate this repository's ESLint setup from eslintrc files to flat config. First find every ESLint config: files named .eslintrc with any or no extension in every directory, an eslintConfig key in package.json, .eslintignore files, and inline eslint-env comments. Read package.json, the lockfile entries for eslint and each config and plugin, and .github/workflows. Run the lint script as it is and record the result. Save eslint --print-config for one source file and one test file. Choose the target ESLint major: read engines.node for the newest releases and the peer ranges of every shared config and plugin in use, compare them with every Node version in the workflow matrix, and pick the newest major that all of them allow; explain the choice. Run the official migration tool on the root config, then check what it left out: nested config files, ignore files and comments that explained rule choices. Bring nested configs over as blocks with a files pattern and keep the explanatory comments. Run lint and sort every new report by cause: a rule the migration dropped, a default that changed in the new major, or a file that was not being linted before. Prove a changed default by running the new ESLint against the old config format. Restore previous behaviour through configuration; do not edit source files to satisfy the linter and do not disable a rule that was on. If the lint script's file patterns skip files, do not change which files are linted; report the skipped files and what linting them would show. Compare --print-config before and after and list any rule whose severity differs. Delete the old config files. Open a pull request with the counts by cause and the open questions.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request that adds `eslint.config.mjs`, deletes both `.eslintrc` files, and changes `package.json` and the lockfile: ESLint 9 and the three packages the flat file imports. The config has two blocks, one for the whole package and one for `test/`, with the original comments about why each rule is overridden carried across. No file under `lib/` or `test/` is edited.

The description accounts for every report the first run produced. For a package like the one above: 40 from the dropped test overrides, 3 from the caught-error default and 3 unused directives, each with what was done. The lint script ends with no errors. The remaining warnings are the unused `eslint-disable` comments, which `eslint --fix` would delete; the agent leaves that one-line cleanup as a suggestion because it edits source. A reviewer checks the config comparison: the same 252 rules at the same severities for a library file and for a test file.

Two things are raised, not changed. The files the script's globs skip, with the errors they contain, since quoting the patterns would make `npm test` fail until those are fixed. And the Airbnb config, which has no flat export and runs through the compatibility layer with a peer range the new ESLint is outside of; replacing it is a style decision for the maintainers.

## Run it on every repository still on .eslintrc

The trigger is a person deciding the old config format has to go, usually because a dependency update is blocked on it. A developer sends this body to `POST /o/{org}/sessions` from a terminal or an MCP client, with a `request_id` that is a UUID made once for the job. The pull request is on the session when the run completes, and a question the agent ends on is answered with a follow-up to `POST /o/{org}/sessions/{id}/messages`, which wakes the same sandbox.

For a group of packages that share a config, a script sends the body once per repository, each with a `request_id` that is a UUID v5 of the repository's full name, so running the script twice starts nothing new. The key queues what it cannot run at once, and its `webhook_url` receives `run.completed` for each run it started. Comparing the counts by cause across repositories shows which problems belong to the shared config and which to one package.

## Why run it on Rush?

The work here is bookkeeping: a snapshot before, a tool run, a diff of several dozen reports, an experiment to prove which ones the new major introduced, and a snapshot after. Each step is a command whose output has to be kept and compared, and that is tedious enough to be skipped by hand. In the run's sandbox the agent installs two ESLint majors side by side, runs both, and every command with its output is in the transcript at `GET /o/{org}/sessions/{id}/messages`.

The result is checkable in a way a hand migration rarely is. The usual hand version ends with a commit that turns off whichever rules started failing. This one comes back with the rule set shown to be unchanged, each new report traced to a cause, and the problems the old setup was hiding written down for someone to decide on.

## Frequently asked questions

### Does the migration tool handle a config in a subdirectory?

No. `@eslint/migrate-config` converts the one file it is given. A second `.eslintrc` in a folder such as `test/` has to become a block with a `files` pattern in the new config, and until it does, every rule it relaxed is back in force. The agent searches for nested configs before running the tool.

### Why do I get new no-unused-vars errors on catch blocks?

ESLint 9 changed that rule's `caughtErrors` default from `none` to `all`, so an unused binding in `catch (err)` is reported. It is a change in ESLint 9, not in flat config. Setting `caughtErrors: "none"` restores the old behaviour; removing the unused bindings is the other fix, and it edits source.

### Can I use eslint-config-airbnb-base with flat config?

Through `FlatCompat` from `@eslint/eslintrc`, yes, and that is what the migration tool generates. Version 15 of the config declares a peer range that ends at ESLint 8, so npm warns when it sits beside ESLint 9. In forwardemail/supertest the rules resolve the same way before and after.

## More ESLint jobs

- [Add an ESLint Check to GitHub Actions for a Next.js App](https://getrush.ai/run/add-lint-to-ci/eslint/)
- [Fix "ESLint couldn't find an eslint.config.* file" after upgrading to ESLint 9](https://getrush.ai/run/fix-eslint-couldnt-find-eslint-config-file/eslint/)
- [Migrate From ESLint and Prettier to Biome](https://getrush.ai/run/migrate-eslint-and-prettier-to-biome/eslint/)

## The same job on other stacks

- [Migrate an Express Project to ESLint Flat Config](https://getrush.ai/run/migrate-eslint-flat-config/express/)
- [Migrate a Lit Component Library to ESLint Flat Config](https://getrush.ai/run/migrate-eslint-flat-config/lit/)
- [Migrate ESLint to Flat Config in a Vite React App](https://getrush.ai/run/migrate-eslint-flat-config/vite-react/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
