API #

defineExtensionMessaging #

// Type
<TProtocolMap>(options: ExtensionMessagingConfig) => {
  sendMessage: SendMessage<TProtocolMap>;
  onMessage: OnMessage<TProtocolMap>;
};

Returns sendMessage and onMessage with types based on your TProtocolMap.

• options ExtensionMessagingConfig: Configures the behavior of sendMessage and onMessage.

sendMessage #

// Type
<TType>(type: TType, data: GetData<TProtocolMap[TType]>, tabId?: number) =>
  Promise<GetResponse<TProtocolMap[TType]>>;

Send a message to the background script, or if a tabId is passed, to the requested tab.

Wherever you're sending the message to, it must have called onMessage with the same message type to recieve it, or you'll get an error.

onMessage #

// Type
<TType>(
  type: TType,
  onRecieved: (
    message: Message<TProtocol<TType>>,
  ) => MaybePromise<GetResponse<TProtocolMap[TType]>>,
) => RemoveOnMessage;

Add a listener that calls the onRecieved callback function when a message of the same type is recieved.

Returns a function that when called, removes the listener.

The Message object contains details about the message that was sent.

If the message type requires a response, you can return a value syncronously or return a Promise of the return type.

Message #

// Type
interface Message<TProtocolMap, TKey> {
  id: number;
  data: GetData<TProtocolMap[TKey]>;
  sender: browser.Runtime.MessageSender;
  timestamp: number;
}

Contains details about the message recieved by the listener.

• id: A auto-incrementing semi-unique identifier for the message. Useful for tracing message chains in debug mode.
• data: The data sent with the message, or undefined if there is no data.
• sender: Details about where the message was sent from. See Runtime.MessageSender for more details.
• timestamp: The MS since epoch when the message was sent.

ProtocolWithReturn #

A utility type for defining a message with a response.

See Protocol Maps for more details.

ExtensionMessagingConfig #

// Type
interface ExtensionMessagingConfig {
  logger?: object | null;
}

• logger (default: console): custom logger for printing sent and recieved messages to the console. Pass null to disable logging.