TypeScript for browser extensions

​

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

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

​

content-typescript

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

​

Generated ambient types

​

Usage with an existing extension

​

Installation

1. 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

2. 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

• .ts source files with no tsconfig.json is a hard error. Create the file next to package.json to fix it.
• A project that declares the typescript dependency but has no tsconfig.json and no .ts sources yet gets a baseline one written for it.

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

• moduleResolution is bundler, which models the Rspack + SWC pipeline. The removed node (node10) mode fails tsc --noEmit on TypeScript 7.
• jsx is react-jsx only when Extension.js detects a JSX framework in the project. Without one, it stays preserve.

​

Automatic 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

{
  "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