webextension-rpc

webextension-rpc

This module provides a Remote Procedure Call abstraction around the message passing that is available to WebExtension (browser extension) scripts. It makes it easier to call a function in the background script from a tab’s content script, or vice versa.

Example use

In background.js:

import { RpcServer } from 'webextension-rpc'
async function myFunc(arg) {
  return arg * 2
}
new RpcServer({ myFunc })

In content_script.js:

import { RpcClient } from 'webextension-rpc'
const myRemoteFunc = new RpcClient().func('myFunc')
await myRemoteFunc(21) // 42!

Note that the remote function always returns a Promise, which resolves with the remote function’s actual return value (if the return value is itself a Promise, its result is awaited too).

Use in TypeScript

When used TypeScript, the type of a remote/proxy function is nearly equal to its original, and can be derived from it automatically. For an example how to do this, see the example folder.

Install

Using NPM

This module is published on npm, as an ES module.

Run npm install webextension-rpc or equivalent, and in your code import what you need, e.g.:

import { RpcClient, RpcServer } from 'webextension-rpc'

API

RpcClient

new RpcClient(options?) (constructor)

Instantiate the RpcClient.

Arguments:

• options (object, optional):
  • options.tabId (number): The id of the tab whose content script is the remote side. Leave undefined or null to invoke functions in the background script (from a content script).

func(functionName, options?)

Create a proxy function that invokes the specified remote function.

Arguments:

• functionName (string, required): name of the function as registered on the remote side.
• options (object, optional): override any options passed to the constructor.

RpcServer

new RpcServer(functions) (constructor)

Register one or more functions to enable remote scripts to call them.

Arguments:

• functions (object, required): An object with a { functionName: function } mapping. Each function will be remotely callable using the given name.

injectRpcInfo

If the special symbol injectRpcInfo is passed as the first argument to a proxy function, this argument will be replaced on the executing side by an RpcInfo object, which contains the following attributes:

• tab: the Tab, from which the call was made, if it was made by a content script.