webext-core

webext-core is a collection of utilities designed to make writing and testing web extensions easier across all browsers. The project is modular, providing specialized packages for common extension development tasks:

• @webext-core/storage: A type-safe API for accessing extension storage, similar to local storage.
• @webext-core/messaging: A simplified, type-safe API for cross-context message passing.
• @webext-core/job-scheduler: Tools to schedule and manage recurring jobs within an extension.
• @webext-core/match-patterns: Utilities for handling and working with web extension match patterns.
• @webext-core/proxy-service: Allows calling functions that execute in a different JavaScript context (e.g., executing logic in the background script from a content script).
• @webext-core/isolated-element: Provides containers with styles isolated from the host page's CSS.
• @webext-core/fake-browser: An in-memory implementation of web extension APIs used for testing extension logic without a real browser.

webext-core is a collection of core libraries and tools designed to simplify building web extensions across all browsers. It provides type-safe wrappers and specialized utilities for common extension tasks like messaging, storage, and job scheduling.

Key packages include:

• @webext-core/messaging: A lightweight, type-safe wrapper for web extension messaging APIs.
• @webext-core/storage: Type-safe wrappers around the storage API based on local storage.
• @webext-core/job-scheduler: A utility to schedule recurring jobs using the Alarms API.
• @webext-core/fake-browser: An in-memory implementation of web extension APIs, intended for testing environments.
• @webext-core/proxy-service: Allows writing services that can be called from any JS context but execute within the background service worker.
• @webext-core/isolated-element: Helps isolate content script UIs from the styles of the host page.

Protocol maps allow you to define types for sendMessage and onMessage in a single interface. When using defineExtensionMessaging<ProtocolMap>(), the data and return types are automatically inferred, eliminating the need to manually pass type parameters to the messaging functions.

In your ProtocolMap interface, define message types as functions where:

• The function name is the message name.
• The function parameters represent the data sent to the message.
• The function return type represents the value returned by the message.

Example interface definitions:

• message1(): void; — No data and no return value.
• message2(data: string): void; — Only data is sent.
• message3(): boolean; — Only a return value is sent back.
• message4(data: string): boolean; — Both data and a return value are used.

interface ProtocolMap {
  message1(): void;
  message2(data: string): void;
  message3(): boolean;
  message4(data: string): boolean;
}

export const { sendMessage, onMessage } = defineExtensionMessaging<ProtocolMap>();

// Usage with automatic inference:
// onMessage('message2', ({ data /* string */ }) /* : void */ => {});
// const res /* : boolean */ = await sendMessage('message3', undefined);

The @webext-core/proxy-service allows you to execute code in the extension's background context from any other part of the extension (like content scripts or UI pages). This is particularly useful for accessing resources that are only available in the background, such as IndexedDB or specific extension APIs.

The Workflow

1. Define a Service: Create a class or object containing the logic you want to run in the background.
2. Define a Key: Create a unique key using ProxyServiceKey<T> to ensure type-safety when calling the service.
3. Register the Service: In your background script, use registerService to instantiate and register the service.
4. Create a Proxy: In your client context (content script, etc.), use createProxyService(KEY) to get a proxy object. Calling methods on this proxy will automatically execute them in the background.

import { createProxyService, registerService } from '@webext-core/proxy-service';

// 1. Define service
class MathService {
  async fibonacci(n: number): Promise<number> { return 0; }
}

// 2. Define key (import ONLY the type of the service)
import type { ProxyServiceKey } from '@webext-core/proxy-service';
import type { MathService } from './MathService';
export const MATH_SERVICE_KEY = 'math-service' as ProxyServiceKey<MathService>;

// 3. Register in background.ts
registerService(MATH_SERVICE_KEY, new MathService());

// 4. Use in anywhere-else.ts
const mathService = createProxyService(MATH_SERVICE_KEY);
await mathService.fibonacci(100);

To communicate between a content script and a webpage (or an injected script), use the specialized messengers from @webext-core/messaging/page.

Choosing a Messenger

• defineCustomEventMessaging: Use this if you do not need to communicate with iframes. It uses the CustomEvent API.
• defineWindowMessaging: Use this if you do need to communicate with iframes. It uses the window.postMessage API.

Configuration: namespace

Both messengers require a namespace option (a unique string). This prevents your extension from accidentally reacting to messages from the page or other extensions.

• For extensions, browser.runtime.id is recommended.
• For injected scripts, you may need to hardcode the extension ID since browser is not available in the page context.

Usage Example

Content Script (Receiver/Sender):

import { websiteMessenger } from './website-messaging';

// ... inject script ...

// Send message to injected script
websiteMessenger.sendMessage('init', { ... });

// Listen for messages from injected script
websiteMessenger.onMessage('somethingHappened', (data) => {
  // React to messages
});

Injected Script (Sender/Receiver):

import { websiteMessenger } from './website-messaging';

// Listen for init
websiteMessenger.onMessage('init', data => {
  // ...

  // Send back to content script
  // Params: action, data, targetOrigin (default '*'), window reference
  websiteMessenger.sendMessage('somethingHappened', { ... }, '*', window.parent);
});

import { defineWindowMessaging } from '@webext-core/messaging/page';

export interface WebsiteMessengerSchema {
  init(data: unknown): void;
  somethingHappened(data: unknown): void;
}

export const websiteMessenger = defineWindowMessaging<WebsiteMessengerSchema>({
  namespace: '<some-unique-string>',
});