What the agent does
The agent starts with the lint command and its inputs, because a flat-config migration changes both. In a Vite application like the apps/react-vite app in alan2207/bulletproof-react, package.json pins eslint to major 8, @typescript-eslint/parser and eslint-plugin ^7.8.0, and a long list of plugins: eslint-plugin-import with eslint-import-resolver-typescript, eslint-plugin-react and react-hooks, jsx-a11y, tailwindcss, testing-library, jest-dom, vitest at ^0.5.4, prettier with eslint-config-prettier, playwright, and eslint-plugin-check-file, which sits in dependencies rather than devDependencies. The lint script is eslint src --ignore-path .gitignore, and --ignore-path does not exist in flat config. lint-staged runs yarn lint and yarn check-types on staged .ts and .tsx files through Husky, and .github/workflows/react-vite-ci.yml runs yarn build, yarn test, yarn lint and yarn check-types on Node LTS. The two sibling apps, apps/nextjs-app and apps/nextjs-pages, still have their own .eslintrc.cjs, so there is no flat config in the repository to copy from.
Then it reads .eslintrc.cjs rule by rule, since the point of the migration is to lose none of them. The file has a root block for plain JavaScript and an override for **/*.ts and **/*.tsx that extends twelve configs, from plugin:import/typescript to plugin:vitest/legacy-recommended, sets settings.react.version to detect and the TypeScript import resolver, and declares the rules that make this codebase what it is: import/no-restricted-paths with zones that stop features/auth importing from features/comments and the other features, forbid features importing from app, and keep components, hooks, lib, types and utils from importing either; import/no-cycle; import/order with named groups, blank lines between them and case-insensitive alphabetical sorting; check-file/filename-naming-convention requiring kebab-case for .ts and .tsx with ignoreMiddleExtensions; and a second override that applies check-file/folder-naming-convention to every folder under src except __tests__. ignorePatterns leaves out node_modules, public/mockServiceWorker.js and generators. The agent records a baseline first: yarn lint on the untouched tree, with the count and the rule ids of any existing findings, so it can show the new config reports the same.
The migration is then mechanical but wide. Each plugin: extend becomes the plugin's flat export: importPlugin.flatConfigs.recommended and .typescript, react.configs.flat.recommended, jsxA11y.flatConfigs.recommended, testingLibrary.configs['flat/react'], jestDom.configs['flat/recommended'], tailwind.configs['flat/recommended'], eslint-plugin-prettier/recommended last, and typescript-eslint's recommended for the parser and its rules. Two packages have to move for that to work: @typescript-eslint at major 7 does not support ESLint 9, so the parser and plugin go to the release that does, and eslint-plugin-vitest 0.5 with its legacy-recommended preset is replaced by the plugin's current package, with the same rules enabled. eslint-plugin-check-file has no preset and is registered under plugins with its two rules copied verbatim, including the files pattern that excludes __tests__ for the folder rule. The .gitignore behaviour comes back through includeIgnoreFile from @eslint/compat plus the three explicit ignore patterns, the lint script drops --ignore-path, and .eslintrc.cjs is deleted. Because package.json has "type": "module", the new file is eslint.config.js with import statements and no require.
Verification is the same four commands CI runs plus one. The agent runs yarn lint and compares its output with the baseline rule for rule, then runs yarn check-types, yarn test for the Vitest suite under src and yarn build, which runs tsc before vite build. The extra step is to prove the restricted-path zones still fire: it adds a temporary import from features/discussions into features/comments, confirms yarn lint reports import/no-restricted-paths, and removes it. It leaves the Next.js apps and their .eslintrc.cjs alone, because the prompt names one app, and notes in the pull request that eslint-plugin-check-file lives in dependencies without moving it, since that is a packaging choice for a reviewer.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Migrate the apps/react-vite application in this repository from .eslintrc.cjs on ESLint 8 to flat config on ESLint 9, keeping every rule and plugin. Read apps/react-vite/package.json, .eslintrc.cjs, .gitignore, .prettierrc, tsconfig.json and .github/workflows/react-vite-ci.yml first. Install with yarn install and record a baseline: run yarn lint on the untouched tree and save the rule ids and counts it reports. Upgrade eslint to version 9 and move the @typescript-eslint parser and plugin, and the vitest plugin, to releases that support it; keep every other plugin at its installed major where its flat config export allows. Write apps/react-vite/eslint.config.js as an ES module that applies the same extends through each plugin's flat export, registers eslint-plugin-check-file with its filename and folder naming rules unchanged, keeps the import/no-restricted-paths zones, import/no-cycle and import/order settings exactly as they are, restores the .gitignore ignores with includeIgnoreFile from @eslint/compat plus the three explicit ignorePatterns, and keeps settings.react.version detect and the TypeScript import resolver. Change the lint script to eslint src, delete .eslintrc.cjs, and leave lint-staged and Husky as they are. Verify: run yarn lint and compare rule for rule with the baseline, then yarn check-types, yarn test and yarn build; add a temporary cross-feature import to confirm import/no-restricted-paths still reports it, then remove it. Do not touch apps/nextjs-app or apps/nextjs-pages. Open a pull request that lists each plugin and the flat export it now uses, pastes the baseline and the new lint output side by side, and quotes every command you ran with its output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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
What comes back is a pull request confined to apps/react-vite: a new eslint.config.js, the deleted .eslintrc.cjs, a package.json whose lint script is eslint src and whose ESLint, @typescript-eslint and Vitest plugin versions moved, with @eslint/compat added, and the yarn.lock entries those changes imply. The body lists every plugin with the flat export it now uses, shows the baseline lint output and the new one side by side, and quotes the lint, check-types, test and build commands with their output, plus the deliberate cross-feature import that the new config rejected.
react-vite-ci.yml runs on the pull request with the same four steps it has always run, so the first green run of yarn lint on ESLint 9 is CI's, not only the sandbox's. The Next.js workflows do not run, since nothing under their apps changed, and lint-staged keeps calling yarn lint on the next commit a developer makes.
A reviewer compares the two lint outputs first, then reads the import/no-restricted-paths zones in the new file against the old, since those encode the project's architecture, and checks the folder-naming override still excludes __tests__. The note about eslint-plugin-check-file sitting in dependencies is theirs to act on.
Run it on every app still on .eslintrc
A team with several front-end apps on legacy ESLint config starts one run per app: POST /o/{org}/sessions with this prompt, the app's path written into input, and the repository in resources, with a request_id per app so a retried request returns the run it already started. In a monorepo like this one, three runs can migrate the three apps in parallel, each in its own sandbox with its own node_modules and its own pull request.
A webhook_url on the API key receives run.completed with data.session_url when each turn ends. Once the turn has finished, a follow-up on POST /o/{org}/sessions/{id}/messages wakes the same sandbox, for instance to ask it to move a plugin to a newer major or to explain one changed rule.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A flat-config migration is a long diff against a short list of expectations: the same rules fire on the same files, the ignore list is the same, and the import boundaries that keep features apart still hold. Checking that by hand means reading two configs side by side and trusting your memory of which plugin exposes which export. In a Rush sandbox the agent records the lint output before, migrates, and shows the output after, with every command in the transcript.
Upgrading ESLint also drags the parser, the Vitest plugin and sometimes more across majors. Doing that on a laptop while the app is open means a broken editor until it is done; doing it in a sandbox means a pull request you can read, a CI run that proves it, and your own tree untouched until you merge.
Frequently asked questions
Will any rule be lost in the migration?
The pull request shows the baseline and the new yarn lint output side by side, and a deliberate cross-feature import that the new config rejects. Each plugin: extend maps to a named flat export, and the two custom check-file rules are copied verbatim, so a lost rule would show up as a difference between the two outputs.
Why do other packages have to change too?
@typescript-eslint at major 7 does not run on ESLint 9, and eslint-plugin-vitest 0.5 only offers a legacy preset. Those two move to releases that support flat config; every other plugin keeps its installed major and is wired through the flat export it already ships. The pull request lists each one.
How does the .gitignore ignore list come back?
--ignore-path was removed in flat config, so the new file reads .gitignore with includeIgnoreFile from @eslint/compat and adds the three patterns the old ignorePatterns listed. The lint script becomes eslint src.
Does it migrate the Next.js apps in the same repository?
No. The prompt names apps/react-vite, and the Next.js apps have their own .eslintrc.cjs files and their own CI workflows. Each can be a separate run with the same prompt and its own path.
More Vite + React jobs
The same job on other stacks
- Migrate a VS Code Extension to ESLint Flat Config (VS Code extension)
- Migrate an ESLint 8 Project from .eslintrc to Flat Config (ESLint)
- Migrate an Express Project to ESLint Flat Config (Express)