API Reference

BaseMessagingConfig

interface BaseMessagingConfig {
  logger?: Logger;
  breakError?: boolean;
}

Shared configuration between all the different messengers.

Properties

• logger?: Logger (default: console)
  The logger to use when logging messages. Set to null to disable logging.
• breakError?: boolean (default: undefined)
  Whether to break an error when an invalid message is received.

CustomEventMessage

interface CustomEventMessage {
  event: CustomEvent;
}

Additional fields available on the Message from a CustomEventMessenger.

Properties

• event: CustomEvent
  The event that was fired, resulting in the message being passed.

CustomEventMessagingConfig

interface CustomEventMessagingConfig extends NamespaceMessagingConfig {}

Configuration passed into defineCustomEventMessaging.

CustomEventMessenger

type CustomEventMessenger<TProtocolMap extends Record<string, any>> =
  GenericMessenger<TProtocolMap, CustomEventMessage, []>;

Messenger returned by defineCustomEventMessenger.

defineCustomEventMessaging

function defineCustomEventMessaging<
  TProtocolMap extends Record<string, any> = Record<string, any>,
>(config: CustomEventMessagingConfig): CustomEventMessenger<TProtocolMap> {
  // ...
}

Creates a CustomEventMessenger. This messenger is backed by the CustomEvent APIs. It can be used to communicate between:

• Content script and website
• Content script and injected script

sendMessage does not accept any additional arguments..

Examples

interface WebsiteMessengerSchema {
  initInjectedScript(data: ...): void;
}

export const websiteMessenger = defineCustomEventMessenger<initInjectedScript>();

// Content script
websiteMessenger.sendMessage("initInjectedScript", ...);

// Injected script
websiteMessenger.onMessage("initInjectedScript", (...) => {
  // ...
})

*

defineExtensionMessaging

function defineExtensionMessaging<
  TProtocolMap extends Record<string, any> = Record<string, any>,
>(config?: ExtensionMessagingConfig): ExtensionMessenger<TProtocolMap> {
  // ...
}

Returns an ExtensionMessenger that is backed by the browser.runtime.sendMessage and browser.tabs.sendMessage APIs.

It can be used to send messages to and from the background page/service worker.

defineWindowMessaging

function defineWindowMessaging<
  TProtocolMap extends Record<string, any> = Record<string, any>,
>(config: WindowMessagingConfig): WindowMessenger<TProtocolMap> {
  // ...
}

Returns a WindowMessenger. It is backed by the window.postMessage API. It can be used to communicate between:

• Content script and website
• Content script and injected script

Examples

interface WebsiteMessengerSchema {
  initInjectedScript(data: ...): void;
}

export const websiteMessenger = defineWindowMessaging<initInjectedScript>();

// Content script
websiteMessenger.sendMessage("initInjectedScript", ...);

// Injected script
websiteMessenger.onMessage("initInjectedScript", (...) => {
  // ...
})

ExtensionMessage

interface ExtensionMessage {
  sender: Runtime.MessageSender;
}

Additional fields available on the Message from an ExtensionMessenger.

Properties

• sender: Runtime.MessageSender
  Information about where the message came from. See Runtime.MessageSender.

ExtensionMessagingConfig

interface ExtensionMessagingConfig extends BaseMessagingConfig {}

Configuration passed into defineExtensionMessaging.

ExtensionMessenger

type ExtensionMessenger<TProtocolMap extends Record<string, any>> =
  GenericMessenger<TProtocolMap, ExtensionMessage, ExtensionSendMessageArgs>;

Messenger returned by defineExtensionMessaging.

ExtensionSendMessageArgs

type ExtensionSendMessageArgs = [tabId?: number];

Send messsage accepts an additional, optional argument tabId. Pass it to send a message to a specific tab from the background script.

You cannot message between tabs directly. It must go through the background script.

GenericMessenger

interface GenericMessenger<
  TProtocolMap extends Record<string, any>,
  TMessageExtension,
  TSendMessageArgs extends any[],
> {
  sendMessage<TType extends keyof TProtocolMap>(
    type: TType,
    data: GetDataType<TProtocolMap[TType]>,
    ...args: TSendMessageArgs
  ): Promise<GetReturnType<TProtocolMap[TType]>>;
  onMessage<TType extends keyof TProtocolMap>(
    type: TType,
    onReceived: (
      message: Message<TProtocolMap, TType> & TMessageExtension,
    ) => void | MaybePromise<GetReturnType<TProtocolMap[TType]>>,
  ): RemoveListenerCallback;
  removeAllListeners(): void;
}

Messaging interface shared by all messengers.

Type parameters accept:

• TProtocolMap to define the data and return types of messages.
• TMessageExtension to define additional fields that are available on a message inside onMessage's callback
• TSendMessageArgs to define a list of additional arguments for sendMessage

GetDataType

type GetDataType<T> = T extends (...args: infer Args) => any
  ? Args["length"] extends 0 | 1
    ? Args[0]
    : never
  : T extends ProtocolWithReturn<any, any>
    ? T["BtVgCTPYZu"]
    : T;

Given a function declaration, ProtocolWithReturn, or a value, return the message's data type.

GetReturnType

type GetReturnType<T> = T extends (...args: any[]) => infer R
  ? R
  : T extends ProtocolWithReturn<any, any>
    ? T["RrhVseLgZW"]
    : void;

Given a function declaration, ProtocolWithReturn, or a value, return the message's return type.

Logger

interface Logger {
  debug(...args: any[]): void;
  log(...args: any[]): void;
  warn(...args: any[]): void;
  error(...args: any[]): void;
}

Interface used to log text to the console when sending and recieving messages.

MaybePromise

type MaybePromise<T> = Promise<T> | T;

Either a Promise of a type, or that type directly. Used to indicate that a method can by sync or async.

Message

interface Message<
  TProtocolMap extends Record<string, any>,
  TType extends keyof TProtocolMap,
> {
  id: number;
  data: GetDataType<TProtocolMap[TType]>;
  type: TType;
  timestamp: number;
}

Contains information about the message recieved.

Properties

• id: number
  A semi-unique, auto-incrementing number used to trace messages being sent.
• data: GetDataType<TProtocolMap[TType]>
  The data that was passed into sendMessage
• type: TType
• timestamp: number
  The timestamp the message was sent in MS since epoch.

MessageSender

interface MessageSender {
  tab?: Tabs.Tab;
  frameId?: number;
  id?: string;
  url?: string;
}

An object containing information about the script context that sent a message or request.

Properties

• tab?: Tabs.Tab
  The $(ref:tabs.Tab) which opened the connection, if any. This property will only be present when the connection was opened from a tab (including content scripts), and only if the receiver is an extension, not an app. Optional.
• frameId?: number
  The $(topic:frame_ids)frame that opened the connection. 0 for top-level frames, positive for child frames. This will only be set when tab is set. Optional.
• id?: string
  The ID of the extension or app that opened the connection, if any. Optional.
• url?: string
  The URL of the page or frame that opened the connection. If the sender is in an iframe, it will be iframe's URL not the URL of the page which hosts it. Optional.

NamespaceMessagingConfig

interface NamespaceMessagingConfig extends BaseMessagingConfig {
  namespace: string;
}

Properties

• namespace: string
  A string used to ensure the messenger only sends messages to and listens for messages from other messengers of the same type, with the same namespace.

ProtocolWithReturn

:::danger Deprecated Use the function syntax instead: https://webext-core.aklinker1.io/guide/messaging/protocol-maps.html#syntax :::

interface ProtocolWithReturn<TData, TReturn> {
  BtVgCTPYZu: TData;
  RrhVseLgZW: TReturn;
}

Used to add a return type to a message in the protocol map.

Internally, this is just an object with random keys for the data and return types.

Properties

• BtVgCTPYZu: TData
  Stores the data type. Randomly named so that it isn't accidentally implemented.
• RrhVseLgZW: TReturn
  Stores the return type. Randomly named so that it isn't accidentally implemented.

Examples

interface ProtocolMap {
  // data is a string, returns undefined
  type1: string;
  // data is a string, returns a number
  type2: ProtocolWithReturn<string, number>;
}

RemoveListenerCallback

type RemoveListenerCallback = () => void;

Call to ensure an active listener has been removed.

If the listener has already been removed with Messenger.removeAllListeners, this is a noop.

WindowMessagingConfig

interface WindowMessagingConfig extends NamespaceMessagingConfig {}

Configuration passed into defineWindowMessaging.

WindowMessenger

type WindowMessenger<TProtocolMap extends Record<string, any>> =
  GenericMessenger<TProtocolMap, {}, WindowSendMessageArgs>;

WindowSendMessageArgs

type WindowSendMessageArgs = [targetOrigin?: string];

For a WindowMessenger, sendMessage requires an additional argument, the targetOrigin. It defines which frames inside the page should receive the message.

See https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#targetorigin for more details.

API reference generated by docs/generate-api-references.ts