TypeScript for browser extensions

Extension.js runs TypeScript across every extension context: background, content scripts, popup, options, and sidebar. It uses the Rspack + SWC pipeline by default. You do not need a separate tsc step, a ts-loader, or an extra bundler rule.

When TypeScript is a good fit

You want safer refactors and clearer contracts across extension contexts.
You share logic between background scripts, content scripts, and UI surfaces.
You need predictable API usage when working with AI-generated code.

Template examples

`new-typescript`

Best for building a new-tab extension with TypeScript defaults already configured.

npx extension@latest create my-extension --template=new-typescript

pnpx extension@latest create my-extension --template=new-typescript

yarn dlx extension@latest create my-extension --template=new-typescript

bunx extension@latest create my-extension --template=new-typescript

deno run -A npm:extension@latest create my-extension --template=new-typescript

Repository: extension-js/examples/new-typescript

`content-typescript`

Best for injecting TypeScript-powered content scripts into existing pages.

npx extension@latest create my-extension --template=content-typescript

pnpx extension@latest create my-extension --template=content-typescript

yarn dlx extension@latest create my-extension --template=content-typescript

bunx extension@latest create my-extension --template=content-typescript

deno run -A npm:extension@latest create my-extension --template=content-typescript

Repository: extension-js/examples/content-typescript

Generated ambient types

For TypeScript projects, Extension.js generates an extension-env.d.ts file at your project root with ambient declarations (browser/runtime globals, EXTENSION_PUBLIC_* env, and bundler types). Both dev and build regenerate it, so editor types and a CI tsc --noEmit stay in sync. Commit it (or git-ignore it) — either works; it’s recreated on the next run.

Usage with an existing extension

Add TypeScript to an existing extension with the steps below.

Installation

Install TypeScript as a development dependency:

npm install -D typescript

pnpm add -D typescript

yarn add -D typescript

bun add -d typescript

deno add -D npm:typescript

Initialize the TypeScript configuration file tsconfig.json:

npx tsc --init

pnpm exec tsc --init

yarn tsc --init

bunx tsc --init

deno run -A npm:typescript/tsc --init

Configuration

TypeScript detection and requirements

Extension.js looks for tsconfig.json next to your package.json.

If TypeScript source files are present and tsconfig.json is missing, Extension.js throws an error and asks you to create one.
If Extension.js detects TypeScript through dependencies or configuration without source files, it can scaffold a baseline tsconfig.json.

Example baseline configuration:

{
  "compilerOptions": {
    "allowJs": true,
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": false,
    "jsx": "react-jsx",
    "lib": ["dom", "dom.iterable", "esnext"],
    "moduleResolution": "node",
    "module": "esnext",
    "noEmit": true,
    "resolveJsonModule": true,
    "strict": true,
    "target": "esnext",
    "skipLibCheck": true
  },
  "exclude": ["node_modules", "dist"]
}

Automatic types

Extension.js generates extension-env.d.ts in your project root during development. This file includes type declarations for Extension.js APIs and browser polyfill types.

// Required Extension.js types for TypeScript projects.
// This file is auto-generated and should not be excluded.
// If you need additional types, consider creating a new *.d.ts file and
// referencing it in the "include" array of your tsconfig.json file.
// See https://www.typescriptlang.org/tsconfig#include for more information.
/// <reference types="extension/types" />

// Polyfill types for browser.* APIs.
/// <reference types="extension/types/polyfill" />

Transpilation vs type-checking

The default bundler pipeline compiles TypeScript but does not run full tsc type-checking as part of bundling. Recommended scripts:

{
  "scripts": {
    "dev": "extension dev",
    "typecheck": "tsc --noEmit"
  }
}

Next steps

Learn how Extension.js handles ECMAScript modules.
Explore styling options like Sass modules.
Read about JavaScript and TypeScript files in browser extensions.
Compare TypeScript support across each browser extension framework.

Video walkthrough

WebAssembly in browser extensions ECMAScript modules in extensions

⌘I

​When TypeScript is a good fit

​Template examples

​new-typescript

​content-typescript

​Generated ambient types

​Usage with an existing extension

​Installation

​Configuration

​TypeScript detection and requirements

​Automatic types

​Transpilation vs type-checking

​Next steps

​Video walkthrough