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.
Room
✓ import { Room } from 'livekit-client';
✗ const Room = require('livekit-client').Room;
The primary class for managing real-time connections. While named import is standard for ESM, CommonJS environments typically use `const livekit = require('livekit-client'); const room = new livekit.Room();`.
RoomEvent
✓ import { RoomEvent } from 'livekit-client';
✗ const RoomEvent = require('livekit-client').RoomEvent;
An enum defining all events dispatched by the `Room` object. For CommonJS, access via `livekit.RoomEvent` after `const livekit = require('livekit-client');`.
VideoPresets
✓ import { VideoPresets } from 'livekit-client';
✗ const VideoPresets = require('livekit-client').VideoPresets;
A utility object containing predefined video resolutions and settings. Use named imports for ESM. For CommonJS, access as `livekit.VideoPresets`.
This quickstart demonstrates how to connect to a LiveKit room, handle remote participant track subscriptions, publish local camera and microphone, and manage room events, suitable for browser-based applications.
import {
LocalParticipant,
LocalTrackPublication,
Participant,
RemoteParticipant,
RemoteTrack,
RemoteTrackPublication,
Room,
RoomEvent,
Track,
VideoPresets,
} from 'livekit-client';
async function setupLiveKitRoom() {
const url = process.env.LIVEKIT_URL ?? 'ws://localhost:7800'; // Replace with your LiveKit server URL
const token = process.env.LIVEKIT_TOKEN ?? 'YOUR_LIVEKIT_TOKEN'; // Replace with your LiveKit access token
if (token === 'YOUR_LIVEKIT_TOKEN') {
console.error('Please provide a LiveKit access token. You can generate one from your LiveKit server or dashboard.');
return;
}
const room = new Room({
adaptiveStream: true,
dynacast: true,
videoCaptureDefaults: {
resolution: VideoPresets.h720.resolution,
},
});
// Ensure a parent element exists to attach video/audio streams
const parentElement = document.getElementById('livekit-container') || document.body;
room.on(RoomEvent.TrackSubscribed, (track: RemoteTrack, publication: RemoteTrackPublication, participant: RemoteParticipant) => {
if (track.kind === Track.Kind.Video || track.kind === Track.Kind.Audio) {
const element = track.attach();
parentElement.appendChild(element);
console.log(`Track subscribed: ${track.kind} from ${participant.identity}`);
}
});
room.on(RoomEvent.TrackUnsubscribed, (track: RemoteTrack, publication: RemoteTrackPublication, participant: RemoteParticipant) => {
const element = track.detach();
element.remove();
console.log(`Track unsubscribed: ${track.kind} from ${participant.identity}`);
});
room.on(RoomEvent.ActiveSpeakersChanged, (speakers: Participant[]) => {
console.log('Active speakers:', speakers.map(s => s.identity));
});
room.on(RoomEvent.Disconnected, (reason: string | undefined) => {
console.log('Disconnected from room:', reason);
});
room.on(RoomEvent.LocalTrackUnpublished, (publication: LocalTrackPublication, participant: LocalParticipant) => {
console.log('Local track unpublished:', publication.trackSid);
});
console.log('Preparing connection...');
room.prepareConnection(url, token);
try {
await room.connect(url, token);
console.log('Connected to room:', room.name);
await room.localParticipant.enableCameraAndMicrophone();
console.log('Published local camera and microphone.');
} catch (error) {
console.error('Failed to connect to LiveKit room:', error);
}
}
// Call the setup function when the DOM is ready in a browser environment
if (typeof document !== 'undefined') {
document.addEventListener('DOMContentLoaded', setupLiveKitRoom);
} else {
// Fallback for non-browser environments or immediate execution
setupLiveKitRoom();
}
Errors
Common errors & fixes
ReferenceError: require is not defined
Attempting to use CommonJS `require()` syntax in an ECMAScript Module (ESM) context (e.g., in a modern React or Vue project without a proper build setup for CJS).
fixReplace `const livekit = require('livekit-client');` with `import * as livekit from 'livekit-client';` or use named imports like `import { Room } from 'livekit-client';`. Failed to connect to room: Invalid token
The LiveKit access token provided is expired, malformed, or does not grant the necessary permissions for the requested room and participant identity.
fixEnsure your token generation logic is correct, the token includes the required `RoomJoin` grant, and the token has not expired. Regenerate the token and verify server-side configuration.
DOMException: Permission denied
The browser has denied access to the user's camera or microphone. This can be due to user choice, insecure context (non-HTTPS), or system-level permissions.
fixEnsure your application is served over HTTPS. Prompt the user for media permissions and provide UI guidance. Check browser and operating system privacy settings for camera/microphone access.
TypeError: livekit.Room is not a constructor
When using `require('livekit-client')` in CommonJS, if the module's export structure doesn't expose `Room` directly as a property, or if the global `LivekitClient` object is not available in a script tag setup.
fixIf using CommonJS, ensure you are accessing `Room` correctly (e.g., `const livekit = require('livekit-client'); const room = new livekit.Room();`). If using a script tag, ensure the global `LivekitClient` object is loaded and use `new LivekitClient.Room()`. Audit
Dependencies
@types/dom-mediacapture-recordoptionalType definitions for WebRTC Media Capture and Streams API extensions for recording. Required for proper TypeScript support in environments leveraging advanced media recording features, but often not a direct runtime dependency.