Twilio Sync Client Library

4.0.0 · active · verified Tue Apr 21

The Twilio Sync JavaScript client library, currently at version 4.0.0, provides a robust solution for real-time state synchronization across browsers, mobile devices, and backend services. It enables two-way, low-latency communication, allowing applications to store and retrieve small amounts of data, such as device states or user settings, and have them instantly reflected everywhere. The library facilitates working with Sync objects like Documents, Lists, and Maps. While a strict release cadence isn't published, major versions introduce significant changes. A key differentiator is its tight integration with the broader Twilio ecosystem for identity management and access control, leveraging Twilio Access Tokens for secure client-side operations, making it suitable for building collaborative real-time features without complex backend infrastructure for state management.

Common errors

```
Error: Token is required for SyncClient.
```
cause The SyncClient constructor was called without a valid access token or with a null/undefined value.

fix Ensure your application fetches a valid Twilio Sync Access Token from a server and passes it to the `SyncClient` constructor.
```
Access Denied. Error code 20101. No active Grant for Sync service for the given identity.
```
cause The provided Access Token does not contain a Sync Grant, or the identity is incorrect, or the token is expired.

fix Verify that your server-side token generation logic includes a Sync Grant (e.g., `new SyncGrant({ serviceSid: 'ISxxx' })`) and that the token is not expired. Also, confirm the identity used to generate the token matches expectations.
```
Sync Error: Document 'MyDocument' not found.
```
cause Attempted to access a Sync Document by a unique name or SID that does not exist or for which the client lacks permissions.

fix Check the document name/SID for typos. Ensure the client's Access Token has the necessary permissions (e.g., `read`, `write`, `manage`) for the Sync Document. Create the document if it's expected to be new (`syncClient.document.create(...)`).

Warnings

breaking Version 4.0.0 likely introduces breaking changes from previous major versions (e.g., v3.x). Always consult the official changelog for detailed migration steps and API adjustments.
Fix: Refer to the Twilio Sync JavaScript Changelog (https://www.twilio.com/docs/sync/javascript/changelog) for specific changes and migration guides.
gotcha A valid Twilio Sync Access Token is critical for client authentication. Tokens must be generated securely on a server-side application or Twilio Function, not directly in the client.
Fix: Set up a server-side endpoint or a Twilio Function to generate and provide short-lived Access Tokens to your client applications. Ensure tokens have appropriate Sync grants and are refreshed before expiration.
gotcha The `Twilio.Sync.Client` global object is only available when including the library via CDN `<script>` tag. When using `npm` with Node.js or bundlers, you must import `SyncClient` as a module.
Fix: For npm installations, use `import { SyncClient } from 'twilio-sync';` (ESM) or `const { SyncClient } = require('twilio-sync');` (CJS).

Install

npm install twilio-sync npm
yarn add twilio-sync yarn
pnpm add twilio-sync pnpm

Imports

SyncClient
wrong:
```
const SyncClient = require('twilio-sync');
```
correct:
```
import { SyncClient } from 'twilio-sync';
```
For modern JavaScript (ESM) environments, use named import. CommonJS `require` is also supported.
SyncClient (CJS)
wrong:
```
import { SyncClient } from 'twilio-sync';
```
correct:
```
const { SyncClient } = require('twilio-sync');
```
This CommonJS syntax is shown in the official README for npm installations.

SyncClient (Type)

wrong:

import { SyncClient } from 'twilio-sync';

correct:

import type { SyncClient } from 'twilio-sync';

When only importing the type definition in TypeScript.

Quickstart

Demonstrates initializing the SyncClient with an access token, opening a Sync Document, listening for updates, and performing a data update operation. Includes basic error handling and shutdown.

import { SyncClient } from 'twilio-sync';

// Obtain a JWT access token from your server-side application or a Twilio Function.
// This token authenticates your client with the Twilio Sync service.
// For development, use process.env.TWILIO_SYNC_TOKEN ?? '' or similar.
const token = process.env.TWILIO_SYNC_TOKEN || '<your-access-token-here>';

if (!token) {
  console.error('Twilio Sync Access Token is required. Please provide it.');
  process.exit(1);
}

const syncClient = new SyncClient(token);

syncClient.document('MyDocument')
  .then(function(document) {
    console.log('Successfully opened Sync Document:', document.sid);
    document.on('updated', function(event) {
      console.log('Received Document update event. New data:', event.data);
    });

    const newData = { temperature: Math.floor(Math.random() * 10) + 20 };
    return document.set(newData);
  })
  .then(function(updateResult) {
    console.log('The Document was successfully updated', updateResult);
  })
  .catch(function(error) {
    console.error('Unexpected error during Sync Document operation:', error);
  });

// Handle client disconnection or token expiration
syncClient.on('connectionStateChanged', (state) => {
  console.log('Sync connection state changed:', state);
});

// Keep the process alive for a bit to receive updates
setTimeout(() => {
  console.log('Shutting down Sync client after a few updates.');
  syncClient.shutdown();
}, 15000);

view raw JSON →