protoo-client

4.0.8 · active · verified Wed Apr 22

protoo-client is the client-side JavaScript library for the protoo signaling framework, designed for building multi-party Real-Time Communication (RTC) applications. It supports both browser and Node.js environments, requiring a compatible WebSocket implementation (native `WebSocket` in browsers, or a library like `ws` in Node.js). The current stable version is 4.0.8, and the project appears to follow semantic versioning with notable breaking changes between major releases, indicating active development. It differentiates itself by offering a minimalist and extensible approach to signaling, focusing specifically on WebRTC use cases.

Common errors

```
peer.send is not a function
```
cause Attempting to use the deprecated `send()` method on a `Peer` instance from `protoo-client` version 4 or newer.

fix Rename `peer.send()` to `peer.request()`. This was a breaking change in v4.
```
ReferenceError: WebSocket is not defined
```
cause This error typically occurs when running `protoo-client` in a Node.js environment without providing a WebSocket implementation. The browser's native `WebSocket` is not available in Node.js.

fix Install the `ws` package (`npm install ws`) and import it. Then, pass an instance of `ws.WebSocket` to the `Peer` constructor, e.g., `new Peer(new WebSocket(url))`.
```
Error: Peer closed
```
cause This error often indicates that the underlying WebSocket connection was closed unexpectedly or failed to establish, and an operation (like `peer.request()`) was attempted on a disconnected peer.

fix Ensure the WebSocket URL is correct, the `protoo-server` is running and accessible, and handle `peer.on('close')` and `peer.on('error')` events to detect and react to disconnections. Re-establish the `Peer` and WebSocket connection if necessary.

Warnings

breaking The `peer.send()` method has been renamed to `peer.request()` in protoo-client v4. Attempting to use `send()` will result in a runtime error.
Fix: Update all calls from `peer.send(method, data)` to `peer.request(method, data)`.
gotcha When using `protoo-client` in Node.js, you must explicitly provide a WebSocket implementation, typically by installing and importing the `ws` package. Browsers provide a native `WebSocket` global.
Fix: For Node.js projects, install `ws` (`npm install ws`) and import it: `import { WebSocket } from 'ws';` then pass an instance to `new Peer(new WebSocket(url))`.

Install

npm install protoo-client npm
yarn add protoo-client yarn
pnpm add protoo-client pnpm

Imports

Peer
wrong:
```
import Peer from 'protoo-client';
```
correct:
```
import { Peer } from 'protoo-client';
```
The core `Peer` class is a named export. Ensure you provide a WebSocket instance (native browser WebSocket or `ws` for Node.js) when instantiating.
protoo-client in CJS
wrong:
```
const protooClient = require('protoo-client');
const Peer = protooClient.Peer;
```
correct:
```
const { Peer } = require('protoo-client');
```
While the latter might work, destructuring directly is the idiomatic CommonJS way to access named exports. ESM is preferred for new projects.

Quickstart

This quickstart demonstrates how to instantiate a protoo-client Peer, establish a WebSocket connection, and handle basic 'open', 'close', 'error', 'request', and 'notification' events. It distinguishes between Node.js and browser WebSocket usage.

import { Peer } from 'protoo-client';
import { WebSocket } from 'ws'; // Only for Node.js. In browsers, use native WebSocket.

const WEBSOCKET_URL = process.env.PROTOO_SERVER_URL || 'wss://your.protoo.server:4443';

async function connectProtoo() {
  let ws;
  if (typeof window === 'undefined') {
    // Node.js environment
    ws = new WebSocket(WEBSOCKET_URL);
  } else {
    // Browser environment
    ws = new WebSocket(WEBSOCKET_URL);
  }

  const peer = new Peer(ws);

  peer.on('open', () => {
    console.log('Protoo Peer connected to server!');
    // Example: Send an initial request
    peer.request('hello', { message: 'Hello from client!' })
      .then(response => console.log('Server response:', response))
      .catch(error => console.error('Request failed:', error));
  });

  peer.on('close', () => {
    console.log('Protoo Peer disconnected.');
  });

  peer.on('error', (error) => {
    console.error('Protoo Peer error:', error.message);
  });

  peer.on('request', async (request, accept, reject) => {
    console.log('Received request from server:', request.method, request.data);
    try {
      if (request.method === 'ping') {
        accept({ pong: 'received' });
      } else {
        reject(new Error('Unknown request method'));
      }
    } catch (error) {
      reject(error);
    }
  });

  peer.on('notification', (notification) => {
    console.log('Received notification from server:', notification.method, notification.data);
  });
}

connectProtoo();

view raw JSON →