Messaging ​

Overview ​

@webext-core/messaging a simplified, type-safe wrapper around the web extension messaging APIs.

Don't like lower-level messaging APIs? Try out @webext-core/proxy-service for a more DX-friendly approach to executing code in the background script.

Installation ​

NPM ​

pnpm i @webext-core/messaging

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

CDN ​

curl -o messaging.js https://cdn.jsdelivr.net/npm/@webext-core/messaging/lib/index.global.js

<script src="/messaging.js"></script>
<script>
  const { defineExtensionMessaging } = webExtCoreMessaging;
</script>

Basic Usage ​

First, define a protocol map:

interface ProtocolMap {
  getStringLength(data: string): number;
}

Then call defineExtensionMessaging, passing your ProtocolMap as the first type parameter.

Export the sendMessage and onMessage methods. These are what the rest of your extension will use to pass messages around.

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

interface ProtocolMap {
  getStringLength(data: string): number;
}

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

Usually the onMessage function will be used in the background and messages will be sent from other parts of the extension.

import { onMessage } from './messaging';

onMessage('getStringLength', message => {
  return message.data.length;
});

import { sendMessage } from './messaging';

const length = await sendMessage('getStringLength', 'hello world');

console.log(length); // 11

Sending Messages to Tabs ​

You can also send messages from your background script to a tab, but you need to know the tabId.

import { onMessage } from './messaging';

onMessage('getStringLength', message => {
  return message.data.length;
});

import { sendMessage } from './messaging';

const length = await sendMessage('getStringLength', 'hello world', tabId);