Skip to main content
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

new-typescript template screenshot Best for building a new-tab extension with TypeScript defaults already configured. 
npx extension@latest create my-extension --template=new-typescript
Repository: extension-js/examples/new-typescript

​
content-typescript

content-typescript template screenshot Best for injecting TypeScript-powered content scripts into existing pages. 
npx 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

  1. Install TypeScript as a development dependency:
  1. Initialize the TypeScript configuration file tsconfig.json:

​
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

​
Video walkthrough