@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

# with your preferred package manager
npm i @addon-core/browser
# or
yarn add @addon-core/browser
# or
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
• 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

• setActionPopup (works in MV2 & MV3):

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

await setActionPopup("popup.html");
// Optional per-tab usage (when you have a tab id):
// await setActionPopup("popup.html", someTabId);

• getCurrentTab:

import { getCurrentTab } from "@addon-core/browser";

const tab = await getCurrentTab();
if (tab?.id) {
  console.log("Current tab id:", tab.id);
}

• onTabUpdated (with unsubscribe):

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

const off = onTabUpdated((tabId, changeInfo, tab) => {
  if (changeInfo.status === "complete") {
    console.log("Tab finished loading:", tabId, tab.url);
  }
});

// Later, to stop listening:
off();

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
• identity
• identityProvider
• omnibox
• pageCapture
• platformKeys
• power
• privacy
• proxy
• search
• sessions
• system.cpu
• system.memory
• system.storage
• tabGroups
• topSites
• tts
• ttsEngine