Skip to main content
Extension.js compiles TypeScript with SWC, which strips types and never checks them. Type checking is a separate step that you run with 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
Those references give you: 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

The extension 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:
The build does not need these packages. SWC never reads the types, so the build succeeds with or without them.

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
From the release after 4.1.41, a copy in 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:
  1. Remove @types/chrome from your project.
  2. Run extension dev or extension build once.
To go back to @types/chrome:
  1. Install @types/chrome as a development dependency.
  2. Run extension dev or extension build once.
On the default setup, the browser global has the native types. For the webextension-polyfill types, import the module:

Pin your own version

The extension 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:
Upgrade extension to 4.1.19 or later. If you stay on an older version, install the package by hand:
On those versions, 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 scaffolded tsconfig.json names it:
tsconfig.json
When Extension.js writes a 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
A copy that already exists is kept up to date either way. Reformatting it, for example with other quotes or without semicolons, does not trigger a rewrite.

Symptoms and fixes

Best practices

  • Treat extension-env.d.ts as build output. Commit it if you like, but never edit it.
  • Declare a type package in your own devDependencies only when you need a specific version of it, or to keep @types/chrome.
  • Run tsc --noEmit in continuous integration. The Extension.js build does not fail on type errors.
  • Run extension build before tsc in continuous integration. dev, build, and start regenerate extension-env.d.ts, and tsc does not.

Next steps