What the agent does
The agent reads the current lint setup end to end, because a Lit project's rules are spread across more than the ESLint file. In a library laid out like lit/lit-element-starter-ts, package.json pins eslint ^8.15.0, @typescript-eslint/eslint-plugin and @typescript-eslint/parser ^5.25.0, lit-analyzer ^1.2.1, prettier ^2.6.2 and typescript ~5.9.0, and the lint script runs lint:lit-analyzer then lint:eslint, the latter as eslint 'src/**/*.ts'. .eslintrc.json sets root: true, extends eslint:recommended and the two @typescript-eslint presets, uses the TypeScript parser with ecmaVersion 2020, enables the browser environment, turns off no-prototype-builtins, ban-types, explicit-function-return-type, explicit-module-boundary-types, no-empty-function and no-non-null-assertion, makes no-explicit-any an error and no-unused-vars a warning with argsIgnorePattern: '^_', and carries two overrides: a node environment for rollup.config.js and web-test-runner.config.js, and no-explicit-any off for *_test.ts and three paths copied from the Lit monorepo that do not exist here. .eslintignore lists node_modules, docs, docs-src, custom-elements.json, web-dev-server.config.js and a misspelt rollup-config.js. tsconfig.json includes only src/**/*.ts, and there is no CI workflow in the repository.
The target is set by what the current ESLint still reads. ESLint 9 made flat config the default, and ESLint 10 removed the eslintrc system entirely, including .eslintignore and the ESLINT_USE_FLAT_CONFIG escape hatch, on Node 20.19 or newer. The agent runs npm install --save-dev eslint@10 typescript-eslint@8 @eslint/js globals and removes @typescript-eslint/eslint-plugin and @typescript-eslint/parser, since the typescript-eslint package re-exports both and its peer range accepts ESLint 8.57 through 10. lit-analyzer is not an ESLint plugin and stays as it is, and eslint-plugin-lit is offered in the pull request as an optional addition rather than installed, because the starter never used it and the job is a migration, not a rule change.
eslint.config.js is written with defineConfig from eslint/config as an ES module, which the "type": "module" in package.json already allows. Its entries are: a global ignores block carrying the .eslintignore paths with the typo corrected to rollup.config.js and my-element.js, my-element.d.ts and test/ added because tsc emits them beside the sources and the old glob in the lint script never reached them; js.configs.recommended and tseslint.configs.recommended scoped to **/*.ts; languageOptions.globals from globals.browser in place of env.browser, with ecmaVersion and sourceType unchanged; the same rules block, except that @typescript-eslint/ban-types is dropped with a comment because typescript-eslint v8 removed the rule and replaced it with no-unsafe-function-type, no-wrapper-object-types and no-empty-object-type, which the agent lists in the pull request so a reviewer can switch any of them on; a globals.node entry for the two config files; and the *_test.ts override with the three monorepo paths deleted. The lint:eslint script becomes eslint ., since ignores now live in the config.
Proof is a before-and-after run. The agent records npm run lint on the unchanged tree, then on the migrated one, and diffs the two reports so the pull request can say which warnings are the same and which are new; no-unused-vars is the one rule whose default options changed between the plugin's v5 and v8, so the explicit argsIgnorePattern keeps its output stable. It runs npx eslint --inspect-config src/my-element.ts to show which config entries apply to a source file, npm run build, and npm test, which runs web-test-runner in Chromium, Firefox and WebKit through the Playwright launchers after the agent installs the browsers, so a type-checking or test regression from the dependency bump would show. .eslintrc.json and .eslintignore are deleted, and the README.md paragraph that tells readers to relax rules by editing .eslintrc.json is updated to name the new file.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Migrate this Lit component library from .eslintrc.json to ESLint flat config. Read package.json, .eslintrc.json, .eslintignore, tsconfig.json, web-test-runner.config.js, rollup.config.js, .eleventy.cjs and README.md first. Run npm run lint on the unchanged tree and keep its output. Upgrade to the current ESLint major and typescript-eslint v8, remove the separate @typescript-eslint plugin and parser packages, and keep lit-analyzer as it is. Write eslint.config.js with defineConfig: the ignore list from .eslintignore with its typo fixed plus the files tsc emits, the recommended JavaScript and TypeScript presets, browser globals, every existing rule override, node globals for the two config files, and the test override without the monorepo-only paths. Drop any rule the new plugin removed and list its replacements in the pull request. Change lint:eslint to eslint ., delete the old files, update the README sentence that names .eslintrc.json, then run npm run lint again and diff the two reports, run npx eslint --inspect-config on a source file, npm run build and npm test with the Playwright browsers installed. Open a pull request with the before and after lint 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 that adds eslint.config.js, deletes .eslintrc.json and .eslintignore, and changes package.json and package-lock.json for the dependency moves, the lint:eslint script and the README.md sentence. The description shows the lint report before and after the migration side by side with the same findings, the --inspect-config output for src/my-element.ts, and the web-test-runner summary across the three browsers.
There is no workflow in this repository, so no check runs on the pull request; the run's record is the evidence, and it keeps the two lint runs, the build and the test run in order. A reviewer who wants a check can take the add-github-actions-ci job next, and the pull request says so.
Before merging, a reviewer decides whether to enable any of the three rules that replaced ban-types, whether to add eslint-plugin-lit and eslint-plugin-wc now that the config can carry them in one entry, and whether the emitted my-element.js files should stay in ignores or be cleaned by the existing clean script before linting. The agent changes no component and no test.
Run it on every component repository still on .eslintrc
A team with several Lit packages started from this template starts one run per repository from its own server: one POST /o/{org}/sessions each, with the repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own .eslintrc.json, so a package that added eslint-plugin-lit gets it carried into the flat config, and one already on eslint.config.js ends with a pull request that says there is nothing to migrate.
After that, an automation in the Project with a github trigger on pull_request.opened and pull_request.synchronize and the prompt "if this pull request adds an ESLint override, check it is in eslint.config.js and not a resurrected .eslintrc file, and say so in a comment" stops the old format from coming back through a copied snippet. The trigger adds the pull request after the prompt and fires only for work by owners, members and collaborators.
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 done by reading the docs alone drifts in ways that only a lint run shows: an ignores entry that no longer matches because .eslintignore used a typo, a rule the new plugin removed that makes ESLint exit before linting anything, or a preset scoped so that the test files lose their override. The agent runs the old and the new config on the same tree in its sandbox and diffs the reports, so the pull request can show the rules behave the same before anyone merges.
Every command stays with the run, from the dependency install to the three-browser test run, and the pull request quotes them. Migrating a dozen component packages at once costs no more attention than one, because each run has its own machine, its own record and its own pull request.
Frequently asked questions
Why go straight to ESLint 10 rather than 9?
ESLint 9 still reads .eslintrc.json behind an environment variable, which lets a half-finished migration pass unnoticed. ESLint 10 removed the eslintrc system and .eslintignore outright, so the only way to lint is the flat config the pull request adds, and typescript-eslint v8 lists ESLint 10 in its peer range. A team that must stay on 9 gets the same eslint.config.js, because the file format is identical.
What happened to the @typescript-eslint/ban-types override?
The rule was removed in typescript-eslint v8 and split into no-unsafe-function-type, no-wrapper-object-types and no-empty-object-type. The old config turned ban-types off, so the agent removes the line and leaves the three replacements at their preset defaults, listing them in the pull request. Keeping the old name would make ESLint refuse to start.
Does lit-analyzer change?
No. It is a separate checker for lit-html templates that the lint script runs before ESLint, and it has no ESLint configuration. The ts-lit-plugin entry in tsconfig.json is likewise untouched. The pull request mentions eslint-plugin-lit as the way to lint templates inside ESLint if the team wants one tool.
Why do the emitted files show up in the ignore list?
Because tsc writes my-element.js, my-element.d.ts and the test/ directory beside src with outDir set to the root, and eslint . would lint them as source. The old eslint 'src/**/*.ts' glob never saw them, so the ignores reproduce that behaviour; the existing clean script removes the same files.
More Lit jobs
The same job on other stacks
- Migrate ESLint to Flat Config in a Vite React App (Vite + React)
- Migrate a VS Code Extension to ESLint Flat Config (VS Code extension)
- Migrate an ESLint 8 Project from .eslintrc to Flat Config (ESLint)