@addon-core/browser

A TypeScript promise-based wrapper for Chrome Extension APIs, supporting both Manifest V2 and V3 across Chrome, Opera, Edge, and other Chromium-based browsers.

Installation

npm

npm i @addon-core/browser

yarn

yarn add @addon-core/browser

pnpm

pnpm add @addon-core/browser

Supported browsers

• Google Chrome (MV2 & MV3)
• Microsoft Edge (Chromium)
• Opera (Chromium) — plus sidebar helpers
• Other Chromium-based browsers (e.g., Brave, Vivaldi, Arc, Yandex, Chromium) — expected to work; behavior aligns with Chrome.
• Firefox — partial support via compatible helpers (e.g., sidebarAction, runtime.getBrowserInfo)
• Apple Safari — limited WebExtensions support; many Chromium-specific APIs are not available, so some helpers won’t work.

Supported Chrome APIs

• action — MV2/MV3 compatible; under the hood uses chrome.action (MV3) or chrome.browserAction (MV2) automatically.
• alarms
• audio
• browsingData
• commands
• contextMenus
• cookies
• documentScan
• downloads
• extension
• history
• i18n
• identity — Chrome full support; Firefox, Edge, and Opera support the portable web auth flow; Safari is not supported.
• idle
• management
• notifications
• offscreen
• permissions
• runtime
• scripting
• sidebar — Unified helpers for Chrome Side Panel (MV3) and Firefox/Opera sidebarAction.
• storage — via separate package: @addon-core/storage
• tabCapture
• tabs
• userScripts
• webNavigation
• webRequest
• windows

Why this package

• Promise-based wrappers for callback-style Chrome APIs.
• All event helpers return an unsubscribe function () => void.
• Concise, consistent function names (easier to read and auto-complete).
• Strong TypeScript types (based on @types/chrome) with explicit event parameter types.
• Tree-shakable build (sideEffects: false) and small, focused utilities.
• MV2/MV3 compatibility handled internally where applicable (e.g., Action, Tabs MV2 helpers, Sidebar cross-browser helpers).

Usage examples

Action API across MV2 and MV3

import {setActionPopup, setBadgeText} from "@addon-core/browser";

await setActionPopup("popup.html");
await setBadgeText("ON");

setActionPopup() works with chrome.action in Manifest V3 and chrome.browserAction in Manifest V2.

Tabs and events

import {getActiveTab, onTabUpdated} from "@addon-core/browser";

const tab = await getActiveTab();

const off = onTabUpdated((tabId, changeInfo) => {
  if (tabId === tab.id && changeInfo.status === "complete") {
    off();
  }
});

Event helpers return an unsubscribe function, making listener lifecycles easy to control.

Context menus and tab messaging

import {createOrUpdateContextMenu, onContextMenusClicked, sendTabMessage} from "@addon-core/browser";

await createOrUpdateContextMenu("save-selection", {
  title: "Save selection",
  contexts: ["selection"],
});

const off = onContextMenusClicked(async (info, tab) => {
  if (info.menuItemId !== "save-selection" || !tab?.id) {
    return;
  }

  await sendTabMessage(tab.id, {
    type: "save-selection",
    text: info.selectionText,
  });
});

createOrUpdateContextMenu() avoids duplicate-menu errors during extension reloads, and sendTabMessage() keeps the background-to-content-script path promise-based.

Helpers

• browserDetection — Best-effort browser detection with BrowserName, BrowserFamily, guessBrowser(), isBrowser(), and isBrowserFamily().

Utilities

In addition to Chrome API wrappers, this package provides a set of low-level utilities for error handling, promise management, and listener safety. While these are primarily used internally, they are also exported via the @addon-core/browser/utils subpath for advanced usage.

For a complete list of utility functions and examples, see the Utilities Documentation.

Not yet covered

These commonly used WebExtensions/Chrome Extension APIs are not wrapped here yet (Chrome OS–only APIs are intentionally omitted). If you’d like to contribute, please see CONTRIBUTING.md and open an issue/PR.

• bookmarks
• contentSettings
• declarativeContent
• declarativeNetRequest (and declarativeNetRequestFeedback)
• desktopCapture
• devtools.* (inspectedWindow, network, panels)
• dns
• fontSettings
• omnibox
• pageCapture
• platformKeys
• power
• privacy
• proxy
• search
• sessions
• system.cpu
• system.memory
• system.storage
• tabGroups
• topSites
• tts
• ttsEngine