# Migrate a Lit Component Library to ESLint Flat Config

Yes. An agent replaces .eslintrc.json and .eslintignore with eslint.config.js, moves to typescript-eslint v8 on ESLint 10, keeps every rule override, and opens a PR.

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

## 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`

```json
{
  "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"
    }
  ]
}
```

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

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.

## 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

- [Upgrade npm Dependencies Weekly for a Lit Component Library](https://getrush.ai/run/upgrade-npm-dependencies/lit/)
- [Add Accessibility Tests to a Lit Component](https://getrush.ai/run/add-accessibility-tests/lit/)
- [Add a Bundle Size Check to a Lit Component](https://getrush.ai/run/add-bundle-size-check/lit/)

## The same job on other stacks

- [Migrate ESLint to Flat Config in a Vite React App](https://getrush.ai/run/migrate-eslint-flat-config/vite-react/)
- [Migrate a VS Code Extension to ESLint Flat Config](https://getrush.ai/run/migrate-eslint-flat-config/vscode-extension/)
- [Migrate an ESLint 8 Project from .eslintrc to Flat Config](https://getrush.ai/run/migrate-eslint-flat-config/eslint/)

## 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/)
