@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

``bash


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):

`ts
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:

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

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

- onTabUpdated (with unsubscribe):

`ts
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