TypeScript#

Build TypeScript browser extensions with zero custom bundler wiring.

Extension.js supports TypeScript across extension contexts (background, content scripts, and page scripts) using the default Rspack + SWC pipeline.

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

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

Repository: extension-js/examples/content-typescript

Using TypeScript with an existing extension#

If you want to add TypeScript support to an existing extension, follow these steps.

Installation#

1. Install TypeScript as a development dependency:

npm install -D typescript

2. Initialize the TypeScript config file tsconfig.json:

npm 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 TypeScript is detected through dependencies/config flow without source files, Extension.js can scaffold a baseline tsconfig.json.

Example baseline config:

{
  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 (dev flow) with references to Extension.js ambient types and 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 transpiles 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.

Video walkthrough#