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.
connect
✓ import { connect } from 'twilio-video';
✗ const { connect } = require('twilio-video');
This is the standard ESM way to import the primary connection function. While `require` works in CommonJS, modern Node.js and browser environments favor ESM imports.
Video (namespace)
✓ import * as Video from 'twilio-video';
✗ import Video from 'twilio-video';
Imports all exports into a namespace object `Video`. There is no default export, so `import Video from 'twilio-video'` would fail. Useful for accessing various modules like `Video.connect` and for type imports in TypeScript.
Video (CommonJS)
✓ const Video = require('twilio-video');
✗ import { Video } from 'twilio-video';
This is the CommonJS syntax for Node.js environments or older browser build setups. If using in a modern ESM-only Node.js project or browser, prefer `import * as Video from 'twilio-video';`.
RemoteParticipant (type)
✓ import type { RemoteParticipant } from 'twilio-video';
✗ import { RemoteParticipant } from 'twilio-video';
For importing only TypeScript types without pulling in runtime values, useful with `isolatedModules` or when types are distinct from runtime values.
This quickstart demonstrates how to connect to a Twilio Video Room, handle participant connections and disconnections, and attach their video and audio tracks to the DOM. It assumes you have a valid Twilio Access Token.
import { connect, Room, LocalParticipant, RemoteParticipant } from 'twilio-video';
// Replace with your actual Access Token and Room Name
const accessToken = process.env.TWILIO_ACCESS_TOKEN ?? ''; // Use environment variable or fetch from a server
const roomName = 'my-super-secret-room';
if (!accessToken) {
console.error('TWILIO_ACCESS_TOKEN environment variable is not set. Please provide a valid access token.');
// In a real application, you might redirect the user or show an error message.
} else {
connect(accessToken, { name: roomName }).then(room => {
console.log(`Connected to Room "${room.name}"`);
// Handle existing participants in the room
room.participants.forEach(participantConnected);
// Listen for new participants connecting
room.on('participantConnected', participantConnected);
// Handle participants disconnecting
room.on('participantDisconnected', participantDisconnected);
// Handle disconnection from the room itself
room.once('disconnected', error => {
console.log('Disconnected from Room:', error);
room.participants.forEach(participantDisconnected);
});
}).catch(error => {
console.error('Failed to connect to Twilio Video Room:', error);
});
}
function participantConnected(participant: RemoteParticipant) {
console.log(`Participant "${participant.identity}" connected`);
const div = document.createElement('div');
div.id = participant.sid;
div.innerText = participant.identity;
document.body.appendChild(div); // Append to body to visualize participants
// When a participant publishes a track, attach it to the DOM
participant.on('trackSubscribed', track => trackSubscribed(div, track));
// Attach already subscribed tracks
participant.tracks.forEach(publication => {
if (publication.isSubscribed) {
trackSubscribed(div, publication.track);
}
});
}
function participantDisconnected(participant: RemoteParticipant) {
console.log(`Participant "${participant.identity}" disconnected`);
document.getElementById(participant.sid)?.remove(); // Remove participant's div from DOM
}
function trackSubscribed(div: HTMLDivElement, track: any) {
// Attach the audio/video track to the participant's div element
div.appendChild(track.attach());
}
Errors
Common errors & fixes
TypeError: Video.connect is not a function
This typically occurs when trying to use a CommonJS `require` syntax (`const Video = require('twilio-video');`) in a browser environment or an ESM-only Node.js project without proper transpilation or bundling.
fixFor modern browser/ESM environments, use `import { connect } from 'twilio-video';`. If using the CDN script tag, access via `const Video = Twilio.Video;`. Ensure your module system matches your import/require style. Unhandled Promise Rejection: AbortError: Failed to set remote answer SDP: Failed to set remote answer sdp. Cannot set SDP offer.
This generic WebRTC error can stem from various issues, including incompatible SDP generated by older `twilio-video` versions interacting with newer browser WebRTC implementations (e.g., the Chrome 137+ SDP munging bug).
fixEnsure you are on `twilio-video@2.32.1` or newer. Verify network connectivity, the validity of your Twilio Access Token, and the correctness of the room name. Check the browser console for more specific WebRTC errors.
TS2307: Cannot find module 'twilio-video' or its corresponding type declarations.
The TypeScript compiler is unable to locate the type definitions for the `twilio-video` package.
fixEnsure `twilio-video` is correctly installed. Since the library ships its own types, you typically don't need `@types/twilio-video`. Check your `tsconfig.json` to ensure `node_modules` is included in `typeRoots` or `include` paths, and consider setting `esModuleInterop` to `true` if mixing module styles.
ReferenceError: require is not defined
This error occurs when `require()` is called in a browser environment, or in a Node.js environment configured exclusively for ECMAScript Modules (ESM) without a CommonJS fallback mechanism.
fixFor browser environments, use the CDN build (which exposes `Twilio.Video` globally) or a bundler like Webpack/Rollup configured for ESM. For ESM Node.js, use `import { connect } from 'twilio-video';`. Video track freezes when video element is offscreen in a Document Picture-in-Picture window.
A bug in earlier `twilio-video` versions would cause video tracks to be automatically switched off by `Client Track Switch Off Control` even when they were visible and rendered in a Document Picture-in-Picture window.
fixUpgrade to `twilio-video@2.32.1` or newer to resolve this issue and ensure video tracks remain active when viewed in Picture-in-Picture windows.
Audit
Dependencies
No dependency data recorded yet.