repository·main·Indexed 20 days ago
https://github.com/serversideup/webext-bridgeA lightweight library providing a simple and consistent API for sending and receiving messages between different parts of a web extension, such as background scripts, content scripts, popups, devtools, options, and windows. It abstracts browser-specific differences for cross-platform compatibility across Chrome, Firefox, Safari, and Edge, and supports type-safe protocols via a ProtocolMap interface.
webext-bridge provides a simple, consistent, and production-ready API for messaging between different parts of a web extension. It abstracts away the complexities and browser-specific differences involved in cross-context communication.
You can send messages between various extension contexts, including:
backgroundcontent-scriptdevtoolspopupoptionswindowThis package is used in production by Bugflow.
webext-bridge is a lightweight library designed to simplify messaging within web extensions. It provides a consistent API for sending and receiving messages across various extension contexts, helping to keep data in sync without the typical complexity of the standard WebExtension messaging APIs.
Supported contexts include:
backgroundcontent-scriptdevtoolspopupoptionswindowMessages in webext-bridge are routed between specific execution contexts. When using the library, you import the specific context module required for your current environment using the pattern: import { ... } from 'webext-bridge/{context}'.
The available contexts are:
content-scriptpopupoptionsbackgrounddevtoolsimport { ... } from 'webext-bridge/content-script'; // Example import patternWhen using sendMessage(msgId, data, destination) or openStream(channelId, initialData, destination), you can target specific environments as the destination:
content-script to devtools: Specifying devtools as the destination will auto-route the payload to the inspecting DevTools page if it is open and listening. If DevTools are not open, the message is queued and delivered once the user opens DevTools and switches to your extension's DevTools panel.devtools to content-script: Specifying content-script as the destination will auto-route the message to the inspected window's top content-script page. If the page is currently loading, the message is queued and delivered once the page is ready and listening.// Example of specifying a destination
sendMessage('my-msg-id', { foo: 'bar' }, 'devtools');
sendMessage('my-msg-id', { foo: 'bar' }, 'content-script');The core communication in webext-bridge relies on two primary methods: sendMessage() to dispatch data and onMessage() to listen for it.
Used to send a message to a specific destination. It accepts three parameters:
messageId: A unique identifier for the message (e.g., an uppercase string or enum).data: The JSON payload to be sent.destination: The target context (e.g., background, popup, or content-script@{tabId}).Used to listen for incoming messages. It accepts two parameters:
messageId: The ID of the message to listen for (must match the sender's messageId).callback: An asynchronous function that handles the message. The callback receives an object containing metadata and the payload.When using webext-bridge to communicate with window contexts, be aware that calling allowWindowMessaging(namespace) in a content script unlocks the window context in that tab.
Unlike standard chrome.runtime APIs, webext-bridge does not automatically restrict which websites can send messages to your extension via the window context. Any webpage can attempt to send messages using the webext-bridge protocol if they know your namespace.
Best Practices:
allowWindowMessaging, verify that the page's window.location.origin matches your expected trusted domains.window messaging with the same caution as window.postMessage. Always verify the sender of a message before performing critical actions or returning sensitive data.Using webext-bridge provides several improvements over standard chrome.runtime messaging APIs:
webext-bridge/popup, webext-bridge/background, etc.), ensuring messages are sent to and handled by the correct parts of the extension without scoping issues.switch/case statements inside a single onMessage listener, you can bind specific actions directly to handler functions using onMessage(action, handler).// Comparison: Built-in messaging requires manual switch/case logic
browser.runtime.onMessage.addListener( ( request, sender, sendResponse ) => {
switch( request.action ){
case "ACTION":
runAction( request.data ).then( sendResponse );
return true;
break;
}
} );The background context is a critical requirement for the library to function. webext-bridge uses the background/event context as a staging area for all messages.
Crucial Requirement: You must load webext-bridge in your background/event page, even if your extension does not explicitly use the background script for sending or receiving messages.
Warning: If webext-bridge is not available in the background page, attempting to send a message from any other context will fail silently.
Browser extensions function like a collection of microservices (popup, background, content scripts, etc.) that need to communicate. Standard browser messaging lacks direct control over message routing and often leads to complex switch statements and callback chains.
webext-bridge solves this by providing:
By default, messaging to or from the window context is restricted for security. To enable it, you must perform two steps within a content script and the target window context:
allowWindowMessaging(<namespace: string>) to unlock message routing for a specific namespace.setNamespace(<namespace: string>) using the same namespace string used in step 1.Using a specific namespace ensures that webext-bridge correctly identifies which messages belong to your extension, preventing collisions if multiple extensions are present on the same page.
// 1. In your content script:
await allowWindowMessaging('my-unique-namespace');
// 2. In the target window context:
await setNamespace('my-unique-namespace');Run the development server to start working on the project. The application will be available at http://localhost:3000.
# npm
npm run dev
# pnpm
pnpm run dev
# yarn
yarn dev
# bun
bun run devYou can install the webext-bridge package using either NPM or Yarn to start passing messages between different components of your browser extension.
# Using NPM
$ npm i webext-bridge
# Using Yarn
$ yarn add webext-bridge