TypeScript Definitions for Chrome Extensions

0.1.425 · active · verified Sun Apr 19

The `chrome-types` package provides official TypeScript declaration files for Chrome Extensions, automatically generated from the Chromium source code. This ensures the definitions are highly accurate and consistently up-to-date with the latest Chrome API changes. Published daily via GitHub Actions, the package reflects Chrome's HEAD revision, making it the most current source for Chrome extension types. It is currently at version 0.1.425. The default `index.d.ts` file includes only Manifest V3 (MV3) and newer types, while a separate `_all.d.ts` file is available for projects requiring definitions for deprecated Platform Apps APIs. This package is crucial for developers building Chrome extensions with TypeScript, providing robust type safety and autocompletion for the global `chrome` object and its various namespaces, distinguishing itself from community-maintained alternatives like `@types/chrome` by its direct origin from the Chromium project itself.

Common errors

```
Cannot find name 'chrome'.
```
cause The TypeScript compiler is not aware of the global `chrome` object types.

fix Ensure `chrome-types` is installed (`npm install --save-dev chrome-types`) and correctly configured in your `tsconfig.json` under `compilerOptions.types` or `compilerOptions.typeRoots`.
```
Property 'tabs' does not exist on type 'typeof chrome'. Did you mean 'tabCapture'?
```
cause Attempting to use a Chrome API (like `chrome.tabs`) that is deprecated or not available in the Manifest V3 context by default, while only the default MV3+ types are loaded.

fix Verify that the API you are using is compatible with Manifest V3. If you intend to use deprecated APIs, ensure you are loading the `_all.d.ts` definition file: `/// <reference types="chrome-types/lib/_all" />`.
```
Type 'X' is not assignable to type 'Y'.
```
cause Strict type checking or changes in Chrome API signatures causing type mismatches.

fix Review the specific type error message. Consult the official Chrome Extensions documentation for the correct API signature. Update your code to match the expected types, or consider narrowing types if the API has become more specific.

Warnings

gotcha By default, `chrome-types` provides definitions tailored for Manifest V3 (MV3) and newer extensions, located in `index.d.ts`. Older or deprecated Platform Apps APIs are excluded from this default.
Fix: If your project requires types for deprecated APIs, explicitly include `chrome-types/lib/_all.d.ts` using `/// <reference types="chrome-types/lib/_all" />` in your TypeScript files or configure `tsconfig.json` appropriately.
gotcha `chrome-types` is an official, auto-generated package, which usually keeps it more up-to-date and accurate with Chromium's latest changes compared to the community-maintained `@types/chrome`. Using both simultaneously can lead to type conflicts.
Fix: Prefer `chrome-types` for Chrome extension development with TypeScript due to its official origin and automated updates. Remove `@types/chrome` if present to avoid conflicts.
gotcha The types are generated from Chromium's HEAD revision, meaning they might occasionally reflect APIs not yet available in the current *stable* Chrome browser release. This can lead to TypeScript errors for valid API calls in older browser versions or vice-versa.
Fix: While `chrome-types` generally tracks current Chrome versions closely, be aware of potential discrepancies. For critical projects, cross-reference API usage with the official Chrome Extensions documentation for your target browser version. Consider pinning `chrome-types` to a specific version if strict API stability is required.

Install

npm install chrome-types npm
yarn add chrome-types yarn
pnpm add chrome-types pnpm

Imports

Global 'chrome' object
wrong:
```
import { chrome } from 'chrome-types'
```
correct:
```
Install 'chrome-types' as a dev dependency and configure `tsconfig.json` to include types (often implicit).
```
This package augments the global `chrome` object. You don't import symbols directly; TypeScript picks up the global declarations from `node_modules/chrome-types/index.d.ts`.
Deprecated Platform Apps APIs
wrong:
```
/// <reference types="chrome-types" /> (does not include deprecated APIs by default)
```
correct:
```
/// <reference types="chrome-types/lib/_all" />
```
The default `index.d.ts` contains MV3+ types only. For older or deprecated Platform Apps APIs, explicitly reference `_all.d.ts` in a `.ts` file or include it via `tsconfig.json` if possible (though reference directives are often clearer for specific files).

Quickstart

This quickstart demonstrates how to configure `tsconfig.json` to enable `chrome-types` and shows a basic Chrome extension background script utilizing `chrome.runtime`, `chrome.storage`, `chrome.action`, and `chrome.scripting` APIs with full TypeScript support.

{
  "compilerOptions": {
    "target": "es2020",
    "module": "esnext",
    "lib": ["es2020", "dom"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "types": ["chrome-types"], // Explicitly include chrome-types
    "moduleResolution": "node"
  },
  "include": ["src/**/*.ts", "manifest.json"],
  "exclude": ["node_modules"]
}

// src/background.ts
chrome.runtime.onInstalled.addListener(() => {
  console.log('Chrome extension installed.');
  chrome.storage.local.set({ greeting: 'Hello, Chrome Extensions!' }, () => {
    console.log('Initial greeting saved.');
  });
});

chrome.action.onClicked.addListener(async (tab) => {
  console.log(`Action clicked on tab: ${tab?.id}`);
  const data = await chrome.storage.local.get('greeting');
  console.log('Retrieved greeting:', data.greeting);
  
  if (tab?.id) {
    // Example: Injecting a content script programmatically
    chrome.scripting.executeScript({
      target: { tabId: tab.id },
      function: () => {
        alert('Hello from your Chrome extension!');
      },
    });
  }
});

view raw JSON →