node-datachannel: WebRTC Data Channels for Node.js and Electron

Common errors

• Error: N-API version 8 is not supported by Node.js x.x.x

  cause The installed `node-datachannel` binary was built for N-API v8 (Node.js >=18.20.0), but is being used with an incompatible Node.js version.
  fix Upgrade your Node.js runtime to version 18.20.0 or newer. For example, using `nvm install 18 && nvm use 18`.

• TypeError: Class constructor PeerConnection cannot be invoked without 'new'

  cause The `PeerConnection` class is being called as a function instead of being instantiated with the `new` keyword.
  fix Instantiate `PeerConnection` using `new PeerConnection(...)` instead of `PeerConnection(...)`.

• Error: CMake 3.21 or greater is required.

  cause When attempting to build `node-datachannel` from source, the system's installed CMake version is older than the minimum required version.
  fix Update your CMake installation to version 3.21 or newer. Check your current version with `cmake --version`.

• TypeError: Cannot read properties of undefined (reading 'PeerConnection')

  cause This error often occurs when attempting to use CommonJS `require('node-datachannel').PeerConnection` with a module that primarily exports via ESM, or when the default export `nodeDataChannel` is not correctly accessed or destructured.
  fix If using ESM, use `import { PeerConnection } from 'node-datachannel';`. If using CommonJS, try `const { PeerConnection } = require('node-datachannel');` or `const nodeDataChannel = require('node-datachannel'); const peer = new nodeDataChannel.PeerConnection(...)`.

Warnings

• breaking The `node-datachannel` package targets N-API version 8, which requires Node.js v18.20.0 or newer. Installing or running on older Node.js versions will likely lead to runtime errors or failed installation.
  Fix: Ensure your Node.js environment is at least v18.20.0. Update using `nvm install 18 && nvm use 18` or similar version management tools.
• breaking The arguments for `addIceCandidate` were updated in v0.25.0 to align with more standard WebRTC API signatures. Code written for older versions might pass incorrect arguments.
  Fix: Review calls to `addIceCandidate` and ensure they conform to the updated signature, typically expecting an `RTCIceCandidate` object and a `mid` string.
• gotcha For users building `node-datachannel` from source, CMake version 3.21 or greater is required. An older version will cause build failures.
  Fix: Upgrade your CMake installation to version 3.21 or newer before attempting to build the package. Check `cmake --version`.
• gotcha Prior to v0.30.0, there were several parameter and return type bugs in the `PeerConnection` wrapper, particularly affecting `RTCDataChannelInit` and `RTCDataChannelEvent` types, which could lead to unexpected behavior or TypeScript errors.
  Fix: Update to v0.30.0 or newer to benefit from fixes to these type and mapping issues, ensuring more reliable API interaction.
• gotcha In versions prior to v0.25.0, calling `RTCDataChannel.close()` could potentially block the event loop, causing performance degradation or unresponsiveness.
  Fix: Upgrade to v0.25.0 or a later version to use the non-blocking `close()` implementation.

Install

• npm install node-datachannel npm
• yarn add node-datachannel yarn
• pnpm add node-datachannel pnpm

Imports

• nodeDataChannel
  wrong:

  const nodeDataChannel = require('node-datachannel');
  nodeDataChannel.initLogger('Debug');

  correct:

  import nodeDataChannel from 'node-datachannel';

  The primary import is a default export, often aliased to `nodeDataChannel`. CommonJS `require` users should access named exports directly or use `.default` where applicable.
• PeerConnection
  wrong:

  import nodeDataChannel from 'node-datachannel';
  const peer = new nodeDataChannel.PeerConnection('Peer1'); // Less idiomatic

  correct:

  import { PeerConnection } from 'node-datachannel';

  `PeerConnection` is a named export. It is idiomatic to destructure it from the module for direct use.
• initLogger
  wrong:

  import nodeDataChannel from 'node-datachannel';
  nodeDataChannel.initLogger('Debug');

  correct:

  import { initLogger } from 'node-datachannel';

  `initLogger` is a named export for configuring the library's logging level.
• WebSocket
  wrong:

  const ws = new nodeDataChannel.WebSocket();

  correct:

  import { WebSocket } from 'node-datachannel';

  The integrated WebSocket client is available as a named export. Ensure it's destructured or accessed correctly.

Quickstart

This quickstart demonstrates how to establish two `PeerConnection` instances, exchange ICE candidates and SDP descriptions, and then create and communicate over a `DataChannel` between them, logging messages in both directions.

import { PeerConnection, initLogger } from 'node-datachannel';

initLogger('Debug');

let dc1 = null;
let dc2 = null;

let peer1 = new PeerConnection('Peer1', {
  iceServers: ['stun:stun.l.google.com:19302']
});

peer1.onLocalDescription((sdp, type) => {
  peer2.setRemoteDescription(sdp, type);
});
peer1.onLocalCandidate((candidate, mid) => {
  peer2.addRemoteCandidate(candidate, mid);
});

let peer2 = new PeerConnection('Peer2', {
  iceServers: ['stun:stun.l.google.com:19302']
});

peer2.onLocalDescription((sdp, type) => {
  peer1.setRemoteDescription(sdp, type);
});
peer2.onLocalCandidate((candidate, mid) => {
  peer1.addRemoteCandidate(candidate, mid);
});
peer2.onDataChannel((dc) => {
  dc2 = dc;
  dc2.onMessage((msg) => {
    console.log('Peer2 Received Msg:', msg);
  });
  dc2.sendMessage('Hello From Peer2');
});

dc1 = peer1.createDataChannel('test');

dc1.onOpen(() => {
  dc1.sendMessage('Hello from Peer1');
});

dc1.onMessage((msg) => {
  console.log('Peer1 Received Msg:', msg);
});