WXT

Appearance

Extension APIs ​

Chrome Docs • Firefox Docs

Different browsers provide different global variables for accessing the extension APIs (chrome provides chrome, firefox provides browser, etc).

WXT merges these two into a unified API accessed through the browser variable.

ts
import { browser } from 'wxt/browser';

browser.action.onClicked.addListener(() => {
  // ...
});

TIP

With auto-imports enabled, you don't even need to import this variable from wxt/browser!

The browser variable WXT provides is a simple export of the browser or chrome globals provided by the browser at runtime:

mjs
export const browser = globalThis.browser?.runtime?.id
  ? globalThis.browser
  : globalThis.chrome;

This means you can use the promise-style API for both MV2 and MV3, and it will work across all browsers (Chromium, Firefox, Safari, etc).

Accessing Types ​

All types can be accessed via WXT's Browser namespace:

ts
import { Browser } from 'wxt/browser';

function handleMessage(message: any, sender: Browser.runtime.MessageSender) {
  // ...
}

Using webextension-polyfill ​

If you want to use the webextension-polyfill when importing browser, you can do so by installing the @wxt-dev/webextension-polyfill package.

See it's Installation Guide to get started.

Feature Detection ​

Depending on the manifest version, browser, and permissions, some APIs are not available at runtime. If an API is not available, it will be undefined.

WARNING

Types will not help you here. The types WXT provides for browser assume all APIs exist. You are responsible for knowing whether an API is available or not.

To check if an API is available, use feature detection:

ts
if (browser.runtime.onSuspend != null) {
  browser.runtime.onSuspend.addListener(() => {
    // ...
  });
}

Here, optional chaining is your best friend:

ts
browser.runtime.onSuspend?.addListener(() => {
  // ...
});

Alternatively, if you're trying to use similar APIs under different names (to support MV2 and MV3), you can do something like this:

ts
(browser.action ?? browser.browser_action).onClicked.addListener(() => {
  //
});