{"id":15872,"library":"twilio-sync","title":"Twilio Sync Client Library","description":"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.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install twilio-sync","lang":"bash","label":"npm"},{"cmd":"yarn add twilio-sync","lang":"bash","label":"yarn"},{"cmd":"pnpm add twilio-sync","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For modern JavaScript (ESM) environments, use named import. CommonJS `require` is also supported.","wrong":"const SyncClient = require('twilio-sync');","symbol":"SyncClient","correct":"import { SyncClient } from 'twilio-sync';"},{"note":"This CommonJS syntax is shown in the official README for npm installations.","wrong":"import { SyncClient } from 'twilio-sync';","symbol":"SyncClient (CJS)","correct":"const { SyncClient } = require('twilio-sync');"},{"note":"When only importing the type definition in TypeScript.","wrong":"import { SyncClient } from 'twilio-sync';","symbol":"SyncClient (Type)","correct":"import type { SyncClient } from 'twilio-sync';"}],"quickstart":{"code":"import { SyncClient } from 'twilio-sync';\n\n// Obtain a JWT access token from your server-side application or a Twilio Function.\n// This token authenticates your client with the Twilio Sync service.\n// For development, use process.env.TWILIO_SYNC_TOKEN ?? '' or similar.\nconst token = process.env.TWILIO_SYNC_TOKEN || '<your-access-token-here>';\n\nif (!token) {\n  console.error('Twilio Sync Access Token is required. Please provide it.');\n  process.exit(1);\n}\n\nconst syncClient = new SyncClient(token);\n\nsyncClient.document('MyDocument')\n  .then(function(document) {\n    console.log('Successfully opened Sync Document:', document.sid);\n    document.on('updated', function(event) {\n      console.log('Received Document update event. New data:', event.data);\n    });\n\n    const newData = { temperature: Math.floor(Math.random() * 10) + 20 };\n    return document.set(newData);\n  })\n  .then(function(updateResult) {\n    console.log('The Document was successfully updated', updateResult);\n  })\n  .catch(function(error) {\n    console.error('Unexpected error during Sync Document operation:', error);\n  });\n\n// Handle client disconnection or token expiration\nsyncClient.on('connectionStateChanged', (state) => {\n  console.log('Sync connection state changed:', state);\n});\n\n// Keep the process alive for a bit to receive updates\nsetTimeout(() => {\n  console.log('Shutting down Sync client after a few updates.');\n  syncClient.shutdown();\n}, 15000);\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Refer to the Twilio Sync JavaScript Changelog (https://www.twilio.com/docs/sync/javascript/changelog) for specific changes and migration guides.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For npm installations, use `import { SyncClient } from 'twilio-sync';` (ESM) or `const { SyncClient } = require('twilio-sync');` (CJS).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure your application fetches a valid Twilio Sync Access Token from a server and passes it to the `SyncClient` constructor.","cause":"The SyncClient constructor was called without a valid access token or with a null/undefined value.","error":"Error: Token is required for SyncClient."},{"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.","cause":"The provided Access Token does not contain a Sync Grant, or the identity is incorrect, or the token is expired.","error":"Access Denied. Error code 20101. No active Grant for Sync service for the given identity."},{"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(...)`).","cause":"Attempted to access a Sync Document by a unique name or SID that does not exist or for which the client lacks permissions.","error":"Sync Error: Document 'MyDocument' not found."}],"ecosystem":"npm"}