> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.
# TypeScript for browser extensions
> Build TypeScript browser extensions with zero config. Extension.js supports TS in background scripts, content scripts, and pages via Rspack and SWC.
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.
```bash npm theme={null}
npx extension@latest create my-extension --template=new-typescript
```
```bash pnpm theme={null}
pnpx extension@latest create my-extension --template=new-typescript
```
```bash yarn theme={null}
yarn dlx extension@latest create my-extension --template=new-typescript
```
```bash bun theme={null}
bunx extension@latest create my-extension --template=new-typescript
```
```bash deno theme={null}
deno run -A npm:extension@latest create my-extension --template=new-typescript
```
Repository: [extension-js/examples/new-typescript](https://github.com/extension-js/examples/tree/main/examples/new-typescript)
### `content-typescript`
Best for injecting TypeScript-powered content scripts into existing pages.
```bash npm theme={null}
npx extension@latest create my-extension --template=content-typescript
```
```bash pnpm theme={null}
pnpx extension@latest create my-extension --template=content-typescript
```
```bash yarn theme={null}
yarn dlx extension@latest create my-extension --template=content-typescript
```
```bash bun theme={null}
bunx extension@latest create my-extension --template=content-typescript
```
```bash deno theme={null}
deno run -A npm:extension@latest create my-extension --template=content-typescript
```
Repository: [extension-js/examples/content-typescript](https://github.com/extension-js/examples/tree/main/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`](/docs/commands/dev) and [`build`](/docs/commands/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:
```bash npm theme={null}
npm install -D typescript
```
```bash pnpm theme={null}
pnpm add -D typescript
```
```bash yarn theme={null}
yarn add -D typescript
```
```bash bun theme={null}
bun add -d typescript
```
```bash deno theme={null}
deno add -D npm:typescript
```
2. Initialize the TypeScript configuration file `tsconfig.json`:
```bash npm theme={null}
npx tsc --init
```
```bash pnpm theme={null}
pnpm exec tsc --init
```
```bash yarn theme={null}
yarn tsc --init
```
```bash bun theme={null}
bunx tsc --init
```
```bash deno theme={null}
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:
```json theme={null}
{
"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.
```ts theme={null}
// 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.
///
// Polyfill types for browser.* APIs.
///
```
#### Transpilation vs type-checking
The default bundler pipeline compiles TypeScript but does not run full `tsc` type-checking as part of bundling.
Recommended scripts:
```json theme={null}
{
"scripts": {
"dev": "extension dev",
"typecheck": "tsc --noEmit"
}
}
```
## Next steps
* Learn how Extension.js handles [ECMAScript modules](/docs/languages-and-frameworks/ecmascript-modules).
* Explore styling options like [Sass modules](/docs/languages-and-frameworks/sass).
* Read about [JavaScript and TypeScript files in browser extensions](/docs/concepts/javascript-typescript-browser-extension-files).
* Compare TypeScript support across each [browser extension framework](/docs/compare).
## Video walkthrough