@webrtc-remote-control/react

Imagine you could simply control a web page opened in a browser (master) from an other page in an other browser (remote), just like you would with a TV and a remote.

webrtc-remote-control lets you do that (based on PeerJS) and handles the disconnections / reconnections, providing a simple API.

Installation

npm install peerjs @webrtc-remote-control/react

This package relies on @webrtc-remote-control/core (the implementation in vanillaJS). Other implementations for popular frameworks are available here.

Usage

peerjs is a peer dependency, so install it alongside this package and import it:

import { Peer } from "peerjs";

getPeerId() returns string | undefined - undefined on a first visit, which peerjs reads as "allocate me an id from the brokering server". Its declarations do not describe that: it declares (), (options) and (id: string, options?), and none of them admits an absent id alongside options. The gap is in the types only, so fix it in the types - declare the missing overload once, rather than branching at runtime or asserting at every call site:

import { Peer as PeerJs } from "peerjs";
import type { PeerOptions } from "peerjs";

export const Peer = PeerJs as typeof PeerJs & {
  new (id: string | undefined, options?: PeerOptions): PeerJs;
};

The examples below assume that Peer.

Direct link to the demo source code: App.tsx / Master.tsx / Remote.tsx

Building with an LLM

demo/counter-react/llm.md is a guide written for coding assistants. It states the parts of the contract the types cannot: that the mode comes from the URL hash, what sessionStorageKey buys you on reload, and which responsibilities sit with this package rather than with your application. Paste it into your assistant's context, or point the assistant at the URL.

Reconnection

A remote that loses its master retries on a backoff and emits remote.reconnecting before each attempt, then remote.reconnect once it is back. useRemote hands out a reconnectNotice that turns that payload into something to show:

const { reconnectNotice } = useRemote();

api.on("remote.reconnecting", (payload) => {
  setStatus(reconnectNotice(payload));
});
api.on("remote.reconnect", () => {
  setStatus(null);
});

The wording is overridable on the provider, and either half may be a value or a function of the payload:

<RemoteProvider
  masterPeerId={masterPeerId}
  init={({ getPeerId }) => new Peer(getPeerId())}
  reconnectNotice={{
    reconnecting: ({ attempt }) => `Reconnecting (attempt ${attempt})...`,
    stalled: "The other screen seems gone. Try reloading.",
  }}
>

A notice does not have to be a string - returning a React node works, and core types each half of it independently. TypeScript infers those types from what you pass to the provider, but a React context is created once, at module scope, so it cannot carry that inference to the hook. Name it there instead:

const { reconnectNotice } = useRemote<ReactNode>();

useRemote hands out one more thing for the same outage: isIgnorableError, which tells the peer-unavailable errors the retry loop provokes from the ones worth showing. Your subscription to your own peer is untouched - the predicate answers a question, and you still write the return:

const { humanizeError, isIgnorableError } = useRemote();

peer.on("error", (error) => {
  if (isIgnorableError(error)) {
    return;
  }
  setErrors([humanizeError(error)]);
});

useMaster has no counterpart for either of these: reconnecting is something a remote does to its master, not the other way round.

See the core README for what the notice decides, and the section after it for what the predicate does and does not claim.

TypeScript

TypeScript types are shipped with the package.

Module format

The package ships as ES modules only. There is no CommonJS or UMD build, so it needs a bundler or a browser that loads <script type="module">.