Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
nodeDataChannel
✓ import nodeDataChannel from 'node-datachannel';
✗ const nodeDataChannel = require('node-datachannel');
nodeDataChannel.initLogger('Debug');
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
✓ import { PeerConnection } from 'node-datachannel';
✗ import nodeDataChannel from 'node-datachannel';
const peer = new nodeDataChannel.PeerConnection('Peer1'); // Less idiomatic
`PeerConnection` is a named export. It is idiomatic to destructure it from the module for direct use.
initLogger
✓ import { initLogger } from 'node-datachannel';
✗ import nodeDataChannel from 'node-datachannel';
nodeDataChannel.initLogger('Debug');
`initLogger` is a named export for configuring the library's logging level.
WebSocket
✓ import { WebSocket } from 'node-datachannel';
✗ const ws = new nodeDataChannel.WebSocket();
The integrated WebSocket client is available as a named export. Ensure it's destructured or accessed correctly.
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);
});
Debug
Known issues
breakingThe `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.fixEnsure your Node.js environment is at least v18.20.0. Update using `nvm install 18 && nvm use 18` or similar version management tools.
affects: <=0.28.0 (prior to strict enforcement/N-API v8 targeting)
breakingThe 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.fixReview calls to `addIceCandidate` and ensure they conform to the updated signature, typically expecting an `RTCIceCandidate` object and a `mid` string.
affects: >=0.25.0
gotchaFor users building `node-datachannel` from source, CMake version 3.21 or greater is required. An older version will cause build failures.fixUpgrade your CMake installation to version 3.21 or newer before attempting to build the package. Check `cmake --version`.
affects: >=0.29.0
gotchaPrior 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.fixUpdate to v0.30.0 or newer to benefit from fixes to these type and mapping issues, ensuring more reliable API interaction.
affects: <0.30.0
gotchaIn versions prior to v0.25.0, calling `RTCDataChannel.close()` could potentially block the event loop, causing performance degradation or unresponsiveness.fixUpgrade to v0.25.0 or a later version to use the non-blocking `close()` implementation.
affects: <0.25.0
Errors
Common errors & fixes
Error: N-API version 8 is not supported by Node.js x.x.x
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.
fixUpgrade 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'
The `PeerConnection` class is being called as a function instead of being instantiated with the `new` keyword.
fixInstantiate `PeerConnection` using `new PeerConnection(...)` instead of `PeerConnection(...)`.
Error: CMake 3.21 or greater is required.
When attempting to build `node-datachannel` from source, the system's installed CMake version is older than the minimum required version.
fixUpdate your CMake installation to version 3.21 or newer. Check your current version with `cmake --version`.
TypeError: Cannot read properties of undefined (reading 'PeerConnection')
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.
fixIf 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(...)`. Audit
Dependencies
No dependency data recorded yet.