@webrtc-remote-control/vue

@webrtc-remote-control/vue

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/vue

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";

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;
};

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

Building with an LLM

demo/counter-vue/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, how state narrows api and peer, 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) => {
  errors.value = [reconnectNotice(payload)];
});
api.on("remote.reconnect", () => {
  errors.value = null;
});

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

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

A notice does not have to be a string, and core types each half of it independently. TypeScript infers those types from what you pass to provideRemote, but the injection key is created once, at module scope, so it cannot carry that inference to the composable. Name it there instead:

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

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;
  }
  errors.value = [humanizeError(error)];
});

The predicate also covers a reload, on both sides, which is why useMaster hands it out too. A page that reloads under its stored id can reach the signaling server before the old page's socket is gone, and is refused with unavailable-id. The provider then builds a new Peer under the same id, waiting a little longer each time, and takes a fresh id after five refusals - once, and on a master only while the page is visible, since its link changes; isIgnorableError is true for those errors while they are being retried. Each attempt is a new Peer, so state.value.peer can change before ready: subscribe in a watch on it.

reconnectNotice has no counterpart on useMaster: 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">.