Skip to content

Repository files navigation

Addonova Browser Social Banner

Version node compatibility License Issues Contributors Sponsor

Unified API's for cross-browser extensions.

Browser extension APIs are similar but not identical. @addonova/browser normalizes the differences that can be normalized safely:

  • one Promise-based method shape for asynchronous APIs;
  • unchanged native events with addListener, removeListener, and hasListener;
  • typed errors for missing APIs, missing permissions, and native failures;
  • support for chrome, chromium, edge, and firefox targets;
  • browser-specific entry points for build-time code elimination.

The package does not generate manifests, inject content scripts, grant permissions, or emulate an API the browser does not provide. See the verified compatibility matrix for the exact support surface.

Installation

npm install @addonova/browser

Requirements:

  • ESM bundler or extension runtime with ES module support.
  • Node.js >=20 for development and the Guchho-based test tooling.
  • No runtime dependency on Addonova Build.

Package entries:

Import Purpose
@addonova/browser Runtime browser detection; default fallback.
@addonova/browser/chrome Fixed Chrome target.
@addonova/browser/chromium Fixed Chromium target.
@addonova/browser/edge Fixed Edge target.
@addonova/browser/firefox Fixed Firefox target.

Quick start

import { action, storage, tabs } from '@addonova/browser';

export async function updateBadge(): Promise<void> {
  const [tab] = await tabs.query({ active: true, currentWindow: true });

  if (tab?.id === undefined) {
    return;
  }

  const { enabled = false } = await storage.local.get('enabled');

  await tabs.sendMessage(tab.id, {
    type: 'set-enabled',
    enabled,
  });
  await action.setBadgeText({ text: enabled ? 'ON' : '' });
}

Register listeners at the top level of a service worker or event page:

import { runtime } from '@addonova/browser';

runtime.onInstalled.addListener((details) => {
  console.log('Installed/updated:', details.reason);
});

Runtime utilities

Typed storage

Use storage.defineItem() to keep a value typed, provide a fallback or lazy initializer, and run versioned migrations:

import { storage } from '@addonova/browser';

interface Settings {
  theme: 'light' | 'dark';
  compact: boolean;
}

const settings = storage.defineItem<Settings>('settings', {
  area: 'local',
  fallback: { theme: 'light', compact: false },
  version: 2,
  migrations: {
    2(value) {
      return { compact: false, ...(value as Partial<Settings>) };
    },
  },
});

const current = await settings.getValue();
await settings.setValue({ ...current, theme: 'dark' });

const stop = settings.watch((newValue, oldValue) => {
  console.log('settings changed', oldValue, newValue);
});
stop();

getMeta() and setMeta() expose the stored item version. removeValue() deletes the value; the next read falls back or initializes again.

Type-safe messaging

Define a message protocol once and share it between the sender and receiver:

import { defineExtensionMessaging } from '@addonova/browser';

interface Protocol {
  ping(data: { at: number }): { at: number };
  add(a: number, b: number): number;
}

const messaging = defineExtensionMessaging<Protocol>();

// Background or any context with a listener.
messaging.onMessage('ping', ({ data, sender }) => {
  console.log('ping from', sender.id, data.at);

  return { at: Date.now() };
});

// Any extension context.
const response = await messaging.sendMessage('ping', { at: Date.now() });

Errors thrown by a handler are serialized and rethrown on the sender. Use defineProxyService() when the service has many methods:

import { defineProxyService } from '@addonova/browser';

const [registerCounter, getCounter] = defineProxyService(
  'counter',
  () => {
    let value = 0;

    return {
      add(amount: number) {
        value += amount;
        return value;
      },
      read() {
        return value;
      },
    };
  },
);

registerCounter();
const counter = getCounter();

await counter.add(2);
await counter.read();
registerCounter.dispose();

Content scripts

createContentScriptContext() tracks timers, animation frames, and listeners and invalidates them together when the content script is unloaded:

import {
  createContentScriptContext,
  injectScript,
} from '@addonova/browser';

const ctx = createContentScriptContext();

ctx.setTimeout(() => {
  console.log('still valid:', ctx.isValid);
}, 1000);

ctx.addEventListener(document, 'click', () => {
  console.log('clicked');
});

ctx.onInvalidated(() => {
  console.log('content script invalidated');
});

await injectScript('/injected.js', { allFrames: false });

Add validateRuntime: false when a test environment does not expose runtime.id.

Content-script UI

Mount UI into the page, a shadow root, or an iframe:

import {
  createIntegratedUi,
  createShadowRootUi,
} from '@addonova/browser';

const inline = createIntegratedUi(ctx, {
  anchor: '#app',
  append: 'last',
  onMount(container) {
    const button = document.createElement('button');
    button.textContent = 'Addonova';
    container.append(button);

    return button;
  },
});

await inline.mount();
inline.remove();

const panel = createShadowRootUi(ctx, {
  anchor: 'body',
  position: 'overlay',
  alignment: 'bottom-right',
  css: ':host { all: initial; } .panel { font: 14px sans-serif; }',
  onMount(container) {
    const element = document.createElement('div');
    element.className = 'panel';
    element.textContent = 'Shadow UI';
    container.append(element);

    return element;
  },
});

await panel.mount();
panel.autoMount();

UI helpers support anchor selectors or elements, append modes (first, last, before, after, replace), position (inline, overlay, modal), alignment, zIndex, and onRemove. autoMount() mounts when the anchor appears, remounts when it is removed, and stops on context invalidation.

i18n

import { createI18nHelper, formatMessage, t } from '@addonova/browser';

const i18nHelper = createI18nHelper({ fallbackToKey: true });

i18nHelper.locale;
i18nHelper.t('greeting', 'Ada');
i18nHelper.raw('greeting', 'Ada');

t('items_selected', ['3']);
formatMessage('Selected $1 item(s)', '3');

t() falls back to the message name when the browser returns an empty string.

Testing

Fake browser

@addonova/browser/testing provides an in-memory implementation of the runtime API. It records storage, tabs, permissions, notifications, alarms, and events, and routes runtime.sendMessage() through onMessage listeners.

import {
  createFakeBrowser,
  installFakeBrowser,
  resetFakeBrowser,
  uninstallFakeBrowser,
} from '@addonova/browser/testing';

const fake = installFakeBrowser({ target: 'chrome' });

await fake.storage.local.set({ enabled: true });
fake.runtime.onMessage.addListener((message, _sender, sendResponse) => {
  sendResponse({ ok: true });
  return true;
});

resetFakeBrowser();
uninstallFakeBrowser();

Use createFakeBrowser() for isolated instances and fakeBrowser for the shared default. reset() clears state while keeping listeners.

Guchho Test setup

Register the setup file so the fake browser is installed before each test:

// guchho.test.config.ts
import { defineConfig } from '@guchho/test';

export default defineConfig({
  setupFiles: ['@addonova/browser/testing/setup'],
});

The setup entry installs the fake browser before the suite, resets it before each test, and uninstalls it afterwards. @guchho/test remains an optional peer dependency.

End-to-end tests

See docs/playwright-e2e.md for a Playwright guide that loads the built extension into a persistent Chromium context.

Browser compatibility

The verified matrix is in docs/compatibility-matrix.md. The short version:

  • Chrome, Chromium, and Edge share one Chromium adapter. Current stable releases target Manifest V3; legacy MV2 is outside current support scope.
  • Edge legacy MV2 is still in Microsoft's deprecation transition and is conditional.
  • Firefox supports both MV2 and MV3. Firefox MV3 uses background.scripts event pages, not a service worker.
  • Firefox 102+ exposes scripting in MV2; Chromium MV2 does not.
  • tabs.executeScript and blocking webRequest APIs are intentionally not exposed. Use scripting and observational webRequest events instead.
  • Firefox does not support notifications.update() or notifications.onButtonClicked.

Run supports() before using an optional API when an extension must work across older browser versions.

API reference

The root export exposes a browser object plus named namespaces:

import {
  action,
  alarms,
  bookmarks,
  browser,
  browserInfo,
  commands,
  contextMenus,
  cookies,
  downloads,
  getAvailability,
  getBrowserInfo,
  i18n,
  isBrowserSupported,
  notifications,
  permissions,
  runtime,
  scripting,
  sessions,
  storage,
  supports,
  tabs,
  webNavigation,
  webRequest,
  windows,
  BrowserApiError,
} from '@addonova/browser';
Namespace Representative methods
runtime id, getManifest, getURL, sendMessage, connect, events
storage local, sync, session, managed, isAreaAvailable
tabs query, get, create, update, remove, reload, sendMessage
windows getCurrent, create, update, remove, getAll
action badge text/color, title, icon, openPopup, onClicked
alarms create, get, getAll, clear, clearAll, onAlarm
commands getAll, onCommand
contextMenus create, update, remove, removeAll, onClicked
notifications create, update, clear, getAll, events
permissions contains, request, remove, getAll, events
scripting executeScript, insertCSS, removeCSS
bookmarks getTree, search, CRUD, events
cookies get, getAll, set, remove, onChanged
downloads download, cancel, search, onChanged
sessions getRecentlyClosed, restore, onChanged
webNavigation navigation event passthrough
webRequest observational request event passthrough
i18n getMessage, getUILanguage, detectLanguage

Shared exports:

  • browserInfo: lazily resolved browser metadata.
  • getBrowserInfo(): resolves the browser name, version, engine, and manifest version.
  • supports('namespace.method'): boolean feature check.
  • getAvailability('namespace.method'): typed availability result with a reason.
  • isBrowserSupported(): whether an extension runtime is available.
  • BrowserApiError: normalized error class with a code.
  • callbackToPromise, promisifyMethod, and event helpers for advanced integrations.

TypeScript examples

All public types are exported from the package root.

import {
  BrowserApiError,
  runtime,
  storage,
  type StorageChange,
} from '@addonova/browser';

interface Settings {
  enabled: boolean;
  theme: 'light' | 'dark';
}

export async function readSettings(): Promise<Settings> {
  const values = await storage.local.get(['enabled', 'theme']);

  return {
    enabled: values.enabled === true,
    theme: values.theme === 'dark' ? 'dark' : 'light',
  };
}

storage.onChanged.addListener(
  (changes: Record<string, StorageChange>, areaName) => {
    if (areaName !== 'local' || changes.enabled === undefined) {
      return;
    }

    console.log('enabled changed:', changes.enabled.newValue);
  },
);

export async function sendHello(): Promise<void> {
  try {
    await runtime.sendMessage({ type: 'hello' });
  } catch (error) {
    if (error instanceof BrowserApiError) {
      console.error(error.code, error.api, error.message);
    }
  }
}

Browser detection

import { browserInfo, getBrowserInfo } from '@addonova/browser';

console.log(browserInfo.name); // 'chrome' | 'chromium' | 'edge' | 'firefox' | 'unknown'
console.log(browserInfo.engine); // 'chromium' | 'gecko' | 'unknown'

const info = getBrowserInfo();
console.log(info);

Detection is feature-first: it checks the extension runtime and API shape before parsing the user agent. Outside an extension, the package returns an unknown environment instead of throwing at import time.

When imported from a fixed subpath such as @addonova/browser/chrome, getBrowserInfo() reports that entry's target and does not consult the build-time target fallback.

8. Feature detection

import { getAvailability, storage, supports } from '@addonova/browser';

if (supports('scripting.executeScript')) {
  // The native API is present.
}

const availability = getAvailability('storage.session');
console.log(availability.available, availability.reason);

if (storage.isAreaAvailable('session')) {
  await storage.session.set({ draft: 'saved for this browser session' });
}

supports() is a fast capability check. getAvailability() explains why a capability is unavailable. Accessing a missing method or event throws BrowserApiError with BROWSER_UNSUPPORTED_API.

9. Browser-specific adapters

Use the root import for runtime detection, or a fixed subpath when the target is known at build time:

import { tabs } from '@addonova/browser/chrome';

Chrome, Chromium, and Edge share the Chromium adapter implementation. Firefox uses a separate Gecko adapter with native Promises. All entries expose the same public surface. Application code should normally import the root; the build integration chooses the subpath.

Browser-specific tree shaking

Use static imports so a bundler can remove unused APIs:

import { tabs } from '@addonova/browser';

const [tab] = await tabs.query({ active: true, currentWindow: true });

Aliasing the root to a browser subpath also removes unrelated adapters:

// Vite-style alias
resolve: {
  alias: {
    '@addonova/browser': '@addonova/browser/chrome',
  },
}

The repository verifies real generated bundles with Guchho in tests/build/tree-shaking.test.ts. A Chrome build retains Chrome plus shared Chromium code, a Firefox build retains Firefox code, and an Edge build retains Edge plus shared Chromium code. Importing only tabs removes unrelated API modules. Dynamic access through the browser object intentionally retains every API. See docs/build-integration.md.

Fixed subpaths also avoid runtime compile-target validation. A bundle that only imports getBrowserInfo() from @addonova/browser/chrome does not retain BROWSER_TARGETS or the build/target fallback logic.

Build-time API selection

The optional compile-time definition __ADDONOVA_BROWSER__ accepts 'chrome', 'chromium', 'firefox', 'edge', or 'auto':

define: {
  __ADDONOVA_BROWSER__: '"chrome"',
}

It makes target-dependent runtime behavior deterministic. It does not replace the subpath alias for code elimination. Invalid or missing values fall back to 'auto'.

Fixed subpaths already know their target, so they skip the compile-time target fallback entirely. This keeps BROWSER_TARGETS and build/target out of fixed-target bundles that only need getBrowserInfo().

Runtime resolution

The default root import resolves the adapter on first use and memoizes it:

  1. Read the build-time target, if present.
  2. Detect the extension runtime and browser API shape.
  3. Select Chrome, Chromium, Edge, or Firefox.
  4. Fall back to an unknown environment that reports explicit unsupported errors.

Runtime resolution always remains available. It does not require Addonova Build, a define, or an alias. Fixed subpaths still locate the extension runtime for manifest metadata, but they use their target provider directly instead of resolving the target name at runtime.

Manifest compatibility

The library does not create or edit manifest.json.

Manifest V3:

{
  "manifest_version": 3,
  "background": { "service_worker": "background.js", "type": "module" },
  "action": { "default_popup": "popup.html" },
  "permissions": ["storage", "tabs"],
  "host_permissions": ["https://example.com/*"]
}

For Firefox MV3, use an event page instead of a service worker:

{
  "manifest_version": 3,
  "background": { "scripts": ["background.js"] },
  "action": { "default_popup": "popup.html" },
  "browser_specific_settings": {
    "gecko": { "id": "example@addonova.dev" }
  }
}

Manifest V2 for Firefox uses browser_action or page_action, host permissions inside permissions, and background scripts or a background page. Chromium legacy MV2 is outside current support scope; Edge MV2 is conditional. See the compatibility matrix for background shapes, webRequestBlocking, scripting, and host-permission differences.

Register event listeners synchronously at the top level of a service worker or event page. Do not wait for asynchronous initialization before registering listeners.

Error handling

import { BrowserApiError, runtime } from '@addonova/browser';

try {
  await runtime.sendMessage({ type: 'ping' });
} catch (error) {
  if (error instanceof BrowserApiError) {
    switch (error.code) {
      case 'BROWSER_UNSUPPORTED_API':
      case 'BROWSER_UNSUPPORTED_ENVIRONMENT':
      case 'BROWSER_PERMISSION_DENIED':
      case 'BROWSER_API_FAILED':
        console.error(error.code, error.api, error.message);
        break;
    }
  }
}

Error codes:

Code Meaning
BROWSER_UNSUPPORTED_API Namespace, method, or event is unavailable.
BROWSER_UNSUPPORTED_ENVIRONMENT No extension runtime was detected.
BROWSER_PERMISSION_DENIED The browser reported a permission failure.
BROWSER_API_FAILED A native API failed for another reason.

No module fakes success, silently no-ops, or falls back to an unrequested API.

Permissions

Permissions are never requested or granted automatically. Declare static permissions in the manifest and request optional permissions from a permitted user gesture:

import { permissions } from '@addonova/browser';

const granted = await permissions.request({
  permissions: ['bookmarks'],
});

if (!granted) {
  console.warn('Bookmarks permission was not granted.');
}

Module permission mapping:

Module Requirement
storage storage
tabs tabs for sensitive fields; host permissions for page access
alarms alarms
contextMenus contextMenus
notifications notifications
bookmarks bookmarks
cookies cookies plus host permissions
downloads downloads
sessions sessions
webNavigation webNavigation
webRequest webRequest plus host permissions
scripting scripting plus host permissions or activeTab
runtime, action, commands, i18n No extra runtime permission

Static host permissions are granted at install time subject to browser policy. permissions.request() asks the user; it can return false or reject. See docs/api-compatibility.md and the compatibility matrix.

Packaging and manual browser smoke-test steps are in docs/integration-testing.md.

Do not publish to npm without explicit authorization. Security issues should be reported according to SECURITY.

License

Addonova is licensed under MIT. Copyright © CodeHemu.