tsc. This page covers how that step resolves chrome.*, browser.*, and process.env.
What Extension.js generates
When a project uses TypeScript,extension dev, extension build, and extension start write an extension-env.d.ts file beside package.json. It is regenerated on every run, so do not edit it.
The file pulls in the ambient types that the extension package publishes:
extension-env.d.ts
The
EXTENSION_* environment keys are typed here too. That is why process.env.EXTENSION_MODE resolves without extra setup.
A project that installs @types/chrome gets a different first reference. The section “Keep @types/chrome” on this page shows it.
When the extension package does not resolve from the project, for example a project that only runs the CLI through npx, the two references find nothing. The generated file then also carries the wildcard module declarations inline, so stylesheet, image, ?raw, and ?url imports still type-check.
Types that install with Extension.js
Theextension package lists the three type packages that its references need as dependencies:
chrome-types is the package that Chrome generates from the Chromium source. Its browser is the native namespace, and its methods return promises. chrome is an alias of it.
chrome-types does not declare the APIs that only Firefox has. Extension.js types Firefox’s browser.sidebarAction and browser.browserAction itself.
They install with extension, so tsc resolves chrome.* and browser.* in a new project without an extra install:
Keep @types/chrome
A project that installs@types/chrome keeps it. That package types chrome, and browser is typed from webextension-polyfill as before.
@types/chrome and chrome-types both declare the chrome global, so the two packages cannot load together. The generated extension-env.d.ts references one or the other. It references @types/chrome when your package.json lists that package:
extension-env.d.ts
node_modules that your package.json does not list, such as one hoisted to a workspace root, counts only for a project on TypeScript 5 or older. TypeScript 6 and later do not load an @types package the project does not reference, so a workspace project on TypeScript 6 or later that wants @types/chrome lists it in its own package.json. Earlier releases referenced @types/chrome whenever node_modules/@types/chrome existed in the project folder or a parent folder.
To move to chrome-types:
- Remove
@types/chromefrom your project. - Run
extension devorextension buildonce.
@types/chrome:
- Install
@types/chromeas a development dependency. - Run
extension devorextension buildonce.
browser global has the native types. For the webextension-polyfill types, import the module:
Pin your own version
Theextension package accepts any version of @types/node and @types/webextension-polyfill. It accepts chrome-types 0.1.460 or later. When your project declares one of them, npm, pnpm, and Bun reuse the copy that your project installs.
When your tsconfig.json has no types array, TypeScript also loads the copy that your project declares. The version in your own package.json wins:
package.json
Projects on Extension.js 4.1.18 or older
Before 4.1.19,extension/types referenced chrome but did not install @types/chrome. A project that calls chrome.* without its own copy fails tsc:
extension to 4.1.19 or later. If you stay on an older version, install the package by hand:
browser has the type any until @types/webextension-polyfill is installed. To type browser.*, install that package too:
Type errors after an upgrade
Earlier releases installed@types/chrome with extension and typed browser from webextension-polyfill. A project that installs @types/chrome keeps those types. A project without @types/chrome moves to chrome-types on upgrade.
After that move, code that passed tsc before can show new type errors. For example, tsc can report names such as chrome.tabs.TabChangeInfo missing.
Install @types/chrome to keep the previous types, then run extension dev or extension build once. Read Cross-browser compatibility for the runtime side of browser.*.
Keep extension-env.d.ts in the include list
The generated file only helps when TypeScript reads it. The scaffoldedtsconfig.json names it:
tsconfig.json
tsconfig.json for a project that has none, that file carries no include array. TypeScript then reads every file under the project folder, so it finds extension-env.d.ts anyway. An include array of your own that omits the file breaks asset imports and the browser global.
From the release after 4.1.39, Extension.js creates the file only when your tsconfig.json would read it beside package.json. That is the case with no include array, with an include that covers the project root, or when include or files names the file. With a narrower include such as ["src"], the file is not created, so add it:
tsconfig.json
Symptoms and fixes
Best practices
- Treat
extension-env.d.tsas build output. Commit it if you like, but never edit it. - Declare a type package in your own
devDependenciesonly when you need a specific version of it, or to keep@types/chrome. - Run
tsc --noEmitin continuous integration. The Extension.js build does not fail on type errors. - Run
extension buildbeforetscin continuous integration.dev,build, andstartregenerateextension-env.d.ts, andtscdoes not.
Next steps
- Read the rest of the TypeScript setup.
- Learn about environment variables that the types declare.
- Review cross-browser compatibility.

