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 { makeRemotelyCallable } from 'webextension-rpc'
async function myFunc(arg) {
  return arg * 2
}
makeRemotelyCallable({ myFunc })

In content_script.js:

import { remoteFunction } from 'webextension-rpc'
const myRemoteFunc = remoteFunction('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 { makeRemotelyCallable } from 'webextension-rpc'

Or copy its lib/index.js and import from that if you prefer (this module has no dependencies).

API

remoteFunction(functionName, { tabId })

Create a proxy function that invokes the specified remote function.

• functionName (string, required): name of the function as registered on the remote side.
• options (object, optional):
  • tabId (number): The id of the tab whose content script is the remote side. Leave undefined to call the background script (from a content script).

makeRemotelyCallable(functions, { insertExtraArg })

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.