Web Extension Messenger

Common errors

• Uncaught ReferenceError: messenger is not defined

  cause Attempting to use `messenger` without proper ESM import or in a CommonJS environment without transpilation.
  fix Ensure you are using `import messenger from 'webext-messenger';` at the top of your module. If in a CommonJS context (e.g., older Node.js scripts), you might need `const messenger = require('webext-messenger').default;` or transpile your code to ESM.

• Error: Could not establish connection. Receiving end does not exist.

  cause A common browser extension error indicating that the target component (e.g., content script, background script) is either not loaded, not listening for messages, or not accessible from the sending context.
  fix Verify that the target script (`background.js`, `content.js`) is correctly registered in your `manifest.json`, is loaded in the browser, and has initialized `messenger.init()` with the correct name and an `onMessage` listener for the message type being sent. Ensure contexts can communicate (e.g., content script cannot directly message another content script).

Warnings

• breaking The package made several changes regarding `webextension-polyfill` usage. It was explicitly used in v0.31.0 and then dropped as a direct dependency in v0.32.0. This means extensions relying on `webextension-polyfill` for the `browser` API object might need to explicitly install and manage it, or adapt to using `chrome` APIs directly if `webext-messenger` no longer polyfills internally.
  Fix: If your extension relies on `browser` APIs, ensure `webextension-polyfill` is installed as a dependency in your project (`npm install webextension-polyfill`) and correctly initialized, or update your code to use `chrome` APIs directly where possible.
• gotcha In v0.35.0, the package dropped `p-retry` and addressed 'retry bugs'. While intended as a fix, this change might alter the retry behavior of message sending for users who implicitly relied on `p-retry`'s specific logic. Applications with sensitive retry requirements should re-test message resilience.
  Fix: Review any parts of your extension where message sending might fail and rely on automatic retries. Test behavior thoroughly with v0.35.0+ to ensure it meets your fault tolerance requirements. Consider implementing custom retry logic if the new default behavior is insufficient.
• breaking The introduction of 'web -> background messaging' in v0.33.0 means web pages can initiate messages to the background script. While a new feature, ensure proper input validation and origin checks are in place within your background script's `onMessage` listeners to prevent potential security vulnerabilities from untrusted web content.
  Fix: When receiving messages in background scripts, always validate the `sender` origin and any received data, especially when messages originate from web pages (e.g., `sender.url` or `sender.origin`). Implement strict allow-lists for message types and data schemas.

Install

• npm install webext-messenger npm
• yarn add webext-messenger yarn
• pnpm add webext-messenger pnpm

Imports

• messenger
  wrong:

  const messenger = require('webext-messenger');

  correct:

  import messenger from 'webext-messenger';

  The primary entry point is a default export, typically imported as `messenger`.
• MessengerError
  wrong:

  import messenger from 'webext-messenger'; messenger.MessengerError; // incorrect direct access

  correct:

  import { MessengerError } from 'webext-messenger';

  Named export for the custom error class, available since v0.33.1.
• * as Messenger

  import * as Messenger from 'webext-messenger';

  While `messenger` is the default, this pattern can be used to access both default and named exports, e.g., `Messenger.default` and `Messenger.MessengerError`.

Quickstart

This quickstart demonstrates basic inter-component communication between a background service worker and a content script using `webext-messenger`. It shows how to initialize messengers in different contexts, set up message listeners, and send messages with data, including handling responses and errors across extension components. The manifest is provided for a complete example.

/* === manifest.json (Manifest V3) === */
{
  "manifest_version": 3,
  "name": "Webext Messenger Demo",
  "version": "1.0",
  "permissions": ["activeTab", "scripting"],
  "background": {
    "service_worker": "background.js"
  },
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["content.js"]
    }
  ],
  "host_permissions": ["<all_urls>"]
}

/* === background.js === */
import messenger from 'webext-messenger';

const backgroundMessenger = messenger.init('background');

backgroundMessenger.onMessage('ping', (data, sender) => {
  console.log('Background received ping:', data, 'from', sender.tab?.url);
  return { response: 'pong from background', receivedData: data };
});

backgroundMessenger.onMessage('logTabUrl', async (data, sender) => {
  console.log('Background received logTabUrl request for tab ID:', data.tabId);
  try {
    const tab = await chrome.tabs.get(data.tabId);
    return { url: tab.url };
  } catch (error) {
    console.error('Error getting tab:', error);
    return { error: error.message };
  }
});

console.log('Background script initialized with webext-messenger');

/* === content.js === */
import messenger from 'webext-messenger';

const contentMessenger = messenger.init('content-script');

contentMessenger.onMessage('alertUser', (message) => {
  alert('Message from background: ' + message);
  return 'Alert shown!';
});

async function sendPingToBackground() {
  console.log('Content script sending ping...');
  try {
    const response = await contentMessenger.sendMessage('background', 'ping', { message: 'Hello from content!' });
    console.log('Content received response from background:', response);
  } catch (error) {
    console.error('Content script failed to send ping:', error);
  }
}

async function requestBackgroundForTabUrl() {
  console.log('Content script requesting current tab URL from background...');
  try {
    const tabId = await new Promise(resolve => chrome.tabs.getCurrent(tab => resolve(tab.id)));
    const response = await contentMessenger.sendMessage('background', 'logTabUrl', { tabId: tabId });
    console.log('Content received tab URL from background:', response.url);
  } catch (error) {
    console.error('Content script failed to request tab URL:', error);
  }
}

// Run these after a short delay to ensure messenger is ready
setTimeout(() => {
  sendPingToBackground();
  requestBackgroundForTabUrl();
}, 1000);

console.log('Content script initialized with webext-messenger');