# Migrate a TypeScript Monorepo from TSLint to ESLint Flat Config

Yes. An agent replaces TSLint with ESLint and typescript-eslint across a monorepo, maps each rule by hand where the converter falls short, and opens a pull request.

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

## What the agent does

The agent runs the existing linter and reads its output closely, not only its exit code. In a monorepo like palantir/documentalist, three packages each define `"lint": "tslint --project ./src"`, the root runs them through `lerna run lint`, and the root `tslint.json` extends `@blueprintjs/tslint-config` and `tslint-plugin-prettier`. `yarn lint` reports success for all three projects. The log tells another story: `The 'prettier' rule threw an error` appears 32 times, once for each TypeScript file, with `TypeError: prettier.getFileInfo.sync is not a function`. The plugin supports Prettier 1 and 2 and the repository installs Prettier 3. TSLint logs a rule that throws and carries on, so lint has not been checking formatting, and the CircleCI config runs `yarn lint` without the separate `format-check` script.

It tries the standard converter and measures how far that gets. `npx tslint-to-eslint-config` reports 90 rules replaced, 9 that behave differently and 6 with no known equivalent: `ban`, `file-header`, `jsx-no-string-ref`, `no-unnecessary-callback-wrapper`, `object-literal-sort-keys` and `prettier`. It writes a 385-line `.eslintrc.js` and asks for nine packages, among them `eslint-plugin-react` for a repository with no `.tsx` file, and `@typescript-eslint/eslint-plugin-tslint`, which runs TSLint inside ESLint for the six leftovers. Neither half works on a current toolchain. ESLint 10 answers `ESLint couldn't find an eslint.config.* file`, because it no longer reads the legacy format, and the bridge plugin's peer range stops at ESLint 8.

So the agent keeps the converter's log as a rule inventory and writes `eslint.config.mjs` itself. Starting from the `typescript-eslint` recommended set is not equivalent either: on this code it raises 13 errors from four rules the TSLint config never enforced, such as `no-explicit-any` and `no-empty-object-type`. The agent turns those four off in the config and lists them as optional follow-up, so the migration does not smuggle in a stricter standard. It then maps the leftovers. `ban` on `Object.assign` and `Object.getOwnPropertyNames` becomes the core `no-restricted-properties` rule with the same messages. `object-literal-sort-keys` becomes `sort-keys`. The JSX rules are dropped with the reason given. `file-header` has no core equivalent, and the agent asks whether to add a header plugin or let the rule go.

The formatting rule is replaced by what the repository already has: the root `format-check` script, which runs `prettier --check`, added to CI as its own step. Run directly, Prettier flags seven files, none of them TypeScript, and the agent reports that as existing drift. It converts the six `tslint:disable` comments in the sources to their ESLint forms, changes each package's `lint` script, removes `tslint.json`, the two TSLint config packages and `tslint` from all three packages, replaces `tslint.autoFixOnSave` in `.vscode/settings.json`, and fixes the CI report step. ESLint no longer ships a JUnit formatter, so the flags that wrote `reports/tslint.xml` now need `eslint-formatter-junit`.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Migrate this monorepo from TSLint to ESLint with typescript-eslint, using a flat eslint.config.mjs at the root. First run the existing lint script and read the whole log, not only the exit code: report any rule that throws or is skipped, and what that means for what lint has really been enforcing. Read tslint.json and every config it extends, each package's lint script, the CI job that runs lint and how it collects reports, and editor settings that mention tslint. Run npx tslint-to-eslint-config and keep its log as an inventory of rules, but do not commit its .eslintrc.js; check whether the ESLint version you install can read that format and whether every package it asks for supports that version. Write the flat config by hand. The goal is the same findings as before: run it, and for every error that comes from a rule TSLint did not enforce, turn that rule off and list it under optional follow-up. For each TSLint rule with no direct equivalent, pick a core or typescript-eslint rule that covers it and say so, or say why it is dropped; ask me before adding a plugin only to keep a file-header rule. Replace the TSLint prettier rule with a direct prettier --check step in CI and report what it flags today without fixing files. Convert tslint:disable comments, update every package's scripts, remove all TSLint packages and config, update editor settings, and keep the CI test report working. Run lint, build and tests before and after. Open a pull request with a table mapping every TSLint rule to its ESLint outcome and the output of every command.",
  "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 `tslint.json`, changes the `lint` and `lint-fix` scripts in each package, swaps the lint packages in the root and package manifests with the lockfile, edits the comment directives in a handful of source files, and updates `.circleci/config.yml` and `.vscode/settings.json`. The description opens with the finding about the old setup: the rule that threw on every file, the version mismatch behind it, and the fact that CI stayed green throughout.

The centre of the description is the rule table. Every rule that was active under TSLint has a row with one of four outcomes: mapped to a named ESLint rule, mapped with a stated behaviour difference, replaced by another tool, or dropped with a reason. A second, shorter table lists the recommended typescript-eslint rules the agent switched off to keep the findings unchanged, with the count of errors each would raise today. That gives the team a ready list for tightening later.

A reviewer checks that the new lint run reports nothing on unchanged code, that build and test totals match the baseline, and that the Prettier step is present in CI as a separate command. They also decide the open question the description ends with, the license header rule. The answer goes back as a follow-up to the same session, and the agent adds the plugin or removes the row.

## Run it on every repository still on TSLint

A linter migration happens once for each repository. Send the body to `POST /o/{org}/sessions` from a terminal or an MCP client, with a `request_id` that is a UUID made for the job. The agent's turn ends with a question about the header rule, and the reply goes to `POST /o/{org}/sessions/{id}/messages`. That wakes the same sandbox, where the dependencies are installed and the baseline logs are still on disk, so the second turn is short.

Where many repositories share one TSLint preset, do the first by hand-off and review its rule table carefully. Then send the remaining repositories from a script, each with a `request_id` that is a UUID v5 of the repository's full name, and paste the approved table into `input` as the mapping to follow. The runs then agree with each other, and the pull requests differ only where a repository's own overrides differ.

## Why run it on Rush?

The interesting facts in this migration come from running things: a lint job that passes while one of its rules crashes, a converter whose output the current ESLint will not load, a recommended preset that is stricter than what it replaces. None of them is visible in the configuration files. The agent installs the repository's locked dependencies in its own sandbox, runs each tool, and keeps the full logs in the transcript at `GET /o/{org}/sessions/{id}/messages`, so each claim in the pull request points at output.

It is also a task with a long, flat middle. Ninety-odd rules have to be looked up one at a time, and the temptation on a laptop is to accept the preset and silence whatever fires. A run has no reason to hurry. It maps every row, tests the result against the unchanged code, and stops only for the one decision that belongs to a person. Meanwhile the developer who started it is free to do other work.

## Frequently asked questions

### Can I just run tslint-to-eslint-config and commit the result?

Not on a current ESLint. The tool writes the legacy `.eslintrc.js` format, which ESLint 10 does not read, and routes unmapped rules through a bridge plugin whose peer range ends at ESLint 8. Its log is still the best inventory of your rules and their differences, and the agent uses it as that.

### Will I get new lint errors after the migration?

Not from this pull request. The request asks for the same findings as before, so any rule that TSLint did not enforce is switched off and listed separately with the number of errors it would raise. Turning those on is a decision for the team, made one rule at a time, with the fixes reviewed on their own.

### What replaces the TSLint prettier rule?

Prettier itself, run as `prettier --check` in CI. Running a formatter through a linter adds a plugin that has to track both tools, and in the fixture this page was written against that plugin had silently stopped working after a Prettier major upgrade. A direct check has no such coupling and fails loudly.

### Does this work for a monorepo with many packages?

Yes. One flat config at the root applies to every package through file globs, and each package's `lint` script calls `eslint` on its own `src`. Package-specific overrides in nested `tslint.json` files become additional config objects with narrower `files` patterns, and the rule table records which package each override came from.

### What about tslint:disable comments in the code?

Each one is rewritten as the matching `eslint-disable` directive with the ESLint rule name, or deleted when the rule it silenced was dropped. The agent lists them by file and line. A comment that disabled a rule with no equivalent is removed, since ESLint can be configured to report directives that silence nothing.

## The same job on other stacks

- [Migrate a VS Code Extension from TSLint to ESLint](https://getrush.ai/run/migrate-tslint-to-eslint/vscode-extension/)

## More jobs like this: Hand off a long task

- [Migrate a Python Test Suite From unittest to pytest](https://getrush.ai/run/migrate-unittest-to-pytest/unittest/)
- [Migrate a Laravel Front End from Vue 2 to Vue 3](https://getrush.ai/run/migrate-vue-2-to-vue-3/laravel/)
- [Migrate a Vue CLI Project to Vite](https://getrush.ai/run/migrate-vue-cli-to-vite/vue-cli/)
- [Migrate a VS Code Extension from Webpack to esbuild](https://getrush.ai/run/migrate-webpack-to-esbuild/vscode-extension/)
- [Migrate a Chrome Extension from Webpack to Vite](https://getrush.ai/run/migrate-webpack-to-vite/chrome-extension/)

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