# Convert a Chrome Extension From JavaScript to TypeScript

Yes. An agent moves your Manifest V3 extension's scripts to strict TypeScript with Chrome's own types, adds a tsc build, keeps the manifest working, and opens a PR.

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

## What the agent does

The agent sizes the extension from its manifest. In an extension like `functional-samples/sample.dnr-rule-manager` in GoogleChrome/chrome-extensions-samples, `manifest.json` is `manifest_version` 3 with a `service_worker` at `service_worker.js`, an action whose popup is `popup.html`, an `options_ui` page `manager.html` that opens in a tab, the `declarativeNetRequest` and `declarativeNetRequestFeedback` permissions and `<all_urls>` host permissions. Three scripts carry the logic: `service_worker.js` restores two dynamic rules on install, a `urlFilter` of `|*?no-cookies=1` and a `regexFilter` of `.*\.google\.com`, both removing the `cookie` header from `main_frame` and `xmlhttprequest` requests, and turns on the matched-request badge; `popup.js` opens the manager tab and lists `getMatchedRules` for the active tab; `manager.js` clones a `<template>` per rule, validates a regex with `isRegexSupported` before enabling Save, and writes through `updateDynamicRules`. The sample has no `package.json` of its own; the repository root pins `eslint` 10 with a flat config that loads `globals.webextensions`, `prettier` 3.9.10 with single quotes and no trailing commas, `chrome-types` 0.1.461, and runs `npm run lint` on Node 24 in `.github/workflows/lint.yml`.

The conversion keeps the loaded files where the HTML and the manifest expect them. Sources move to `src/service_worker.ts`, `src/popup.ts` and `src/manager.ts`; a `tsconfig.json` with `strict`, `target` and `lib` at `ES2022` plus `DOM`, `types: ["chrome-types"]` and `outDir: "dist"` compiles them; and a `package.json` in the extension directory adds `typescript` and `chrome-types` as dev dependencies with a `build` script that runs `tsc` and copies `manifest.json`, the two HTML files, `manager.css` and `icons/` into `dist/`, so `dist/` is the directory loaded unpacked. The old `.js` files are deleted, `dist/` is added to `.gitignore`, and the README's load-unpacked step points at `dist/`. The scripts stay classic scripts rather than modules, because the HTML loads them with plain `<script src>` tags and the service worker is registered without `type: module`.

Strict mode finds the places where the JavaScript assumed too much. `ruleItemTemplate.content.cloneNode(true).children[0]` is a `DocumentFragment` clone whose first child must be narrowed to `HTMLElement`; every `querySelector('.rule-id')` becomes `querySelector<HTMLInputElement>` so `.value` and `.checked` type-check; `window.open()` can return null and the View button now handles that; `(await chrome.tabs.query({ active: true }))[0].id` is `number | undefined` and the popup guards it; and `getCurrentRuleValues` returns an `id` of `'NEW' | number`, which the agent names as a type rather than letting `parseInt` and a string share a variable. `conditionType` becomes the literal union `'urlFilter' | 'regexFilter'`, and `rule.condition[conditionType]` indexes `chrome.declarativeNetRequest.RuleCondition` cleanly because of it. The rule objects passed to `updateDynamicRules` are typed as `chrome.declarativeNetRequest.Rule`, which catches a mistyped `resourceTypes` value at compile time.

Verification is a build and a lint, then a load. `npm run build` in the extension directory must produce `dist/` with no diagnostics; `npm run lint` at the root must still pass, which means adding the emitted `dist/**/*.js` to the ESLint ignores and `.prettierignore` so the formatter checks sources, not output. The agent then launches Chromium under Puppeteer with `--load-extension=dist` and `--disable-extensions-except=dist`, the way `functional-samples/tutorial.puppeteer` in the same repository does, waits for the service worker target, and evaluates `chrome.declarativeNetRequest.getDynamicRules()` in it to confirm the two default rules were written by the compiled worker. The pull request pastes that list and the `tsc` and lint output.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Convert this Manifest V3 Chrome extension from JavaScript to TypeScript. Read manifest.json, every .js and .html file in the extension, README.md, and the repository root's package.json, eslint.config.js and .prettierrc.json first. Move the scripts to src/*.ts and add a tsconfig.json with strict mode, ES2022 target and lib with DOM, chrome-types as the types, and dist as the output; add a package.json in the extension directory with typescript and chrome-types as dev dependencies and a build script that runs tsc and copies the manifest, HTML, CSS and icons into dist. Keep the scripts as classic scripts, not modules. Type the DOM lookups with querySelector generics, narrow window.open and tab ids, type the rule objects as chrome.declarativeNetRequest.Rule and make the condition type a literal union. Delete the old .js files, ignore dist in .gitignore, ESLint and Prettier, and update the README's load-unpacked path. Run npm run build, the root npm run lint, and a Puppeteer smoke check that loads dist and reads getDynamicRules from the service worker. Open a pull request with the tsc, lint and smoke-check 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

The pull request renames the three scripts into `src/` as `.ts`, adds `tsconfig.json` and the extension's `package.json`, updates `.gitignore`, the ESLint ignores, `.prettierignore` and the README, and leaves `manifest.json`, the HTML and the CSS byte-for-byte as they were apart from nothing at all, since the compiled files keep their names. Its description pastes a clean `tsc` run, the root lint result, and the two dynamic rules read back from the loaded extension's service worker.

Each type the conversion introduced is small and named in the diff: the rule id union, the condition-type union and the rule values record. Where strict mode exposed a real gap, such as the popup assuming an active tab always has an id, the guard is in the code and the description says why.

Before merging, a reviewer loads `dist/` unpacked once, opens the manager page and saves a rule, and decides whether the repository's CI should add this directory to its `samples` matrix so `npm run build` runs on every pull request.

## Run it on every extension still in JavaScript

A team with several extensions sends this body once per repository to `POST /o/{org}/sessions` from the terminal or a script, each with its own 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 manifest: an extension whose scripts are ES modules keeps `type: module` and gets `module: ES2022`, one with a bundler already in place gets TypeScript wired into that bundler instead of a plain `tsc` build, and one with tests gets them converted in the same pass.

Each run opens its own pull request on its own branch, and the person who started the batch reads every `tsc` and lint result from `GET /o/{org}/sessions`.

## Why run it on Rush?

A conversion is finished when the compiler, the linter and the browser all agree, and each disagreement points at a specific line: a DOM lookup that needs a generic, a tab id that may be missing, a rule object with a field Chrome does not accept. The agent runs that loop in its own sandbox, reads each diagnostic, and fixes the line it names, with the commands and their output kept in the transcript.

Loading the result in a real browser is the step that usually gets skipped. The agent does it under Puppeteer with the compiled `dist/`, reads the rules back from the service worker, and puts the list in the pull request, so review is about the types and not about whether the extension still starts.

## Frequently asked questions

### Why chrome-types and not @types/chrome?

The repository already pins `chrome-types`, Google's own generated declarations, at the root, so the extension uses the package its maintainers chose. In another repository the agent uses whichever of the two is already installed, and `@types/chrome` when neither is.

### Does the extension need a bundler now?

No. The three scripts have no imports and the HTML loads them as classic scripts, so `tsc` emitting one JavaScript file per source into `dist/` is the whole build. A bundler is added only when a script imports another or a dependency from npm.

### What changes for someone loading the extension unpacked?

The directory to load becomes `dist/` after `npm run build`, and the README says so. The manifest, the HTML and the file names inside `dist/` are the same as before, so bookmarks to the manager page and the stored dynamic rules are unaffected.

### Will the root lint keep passing?

Yes. The root config lints `**/*.js`, which would now include the emitted files, so `dist/` is added to the ESLint ignores and to `.prettierignore`, and the pull request shows `npm run lint` passing at the root. Linting the `.ts` sources with `typescript-eslint` is offered as a follow-up rather than added in the same change.

### How does the smoke check run without a display?

Puppeteer launches Chromium in headless mode with `--load-extension` and `--disable-extensions-except` pointing at `dist/`, which is the same approach the repository's `tutorial.puppeteer` sample uses. The check waits for the extension's service worker target and evaluates `getDynamicRules` in it; it does not open the popup or the manager page.

## More Chrome extension jobs

- [Migrate a Chrome Extension from Jest to Vitest](https://getrush.ai/run/migrate-jest-to-vitest/chrome-extension/)
- [Replace setTimeout Polling With chrome.alarms in a Chrome Extension](https://getrush.ai/run/migrate-to-chrome-alarms/chrome-extension/)
- [Migrate a Chrome Extension from Webpack to Vite](https://getrush.ai/run/migrate-webpack-to-vite/chrome-extension/)

## The same job on other stacks

- [Convert an Ember App From JavaScript to TypeScript](https://getrush.ai/run/convert-javascript-to-typescript/ember/)
- [Convert an Express App from JavaScript to TypeScript](https://getrush.ai/run/convert-javascript-to-typescript/express/)
- [Convert Firebase Cloud Functions From JavaScript to TypeScript](https://getrush.ai/run/convert-javascript-to-typescript/firebase-functions/)

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