@tldraw/sync

Active contributors: David Sheldrick, Mitja Bezenšek, Steve Ruiz

Purpose

@tldraw/sync is the React-facing wrapper around @tldraw/sync-core. It exposes two hooks — useSync() for production and useSyncDemo() for the public demo backend — that wire a tldraw store to a remote room and return a TLStoreWithStatus you can pass into <Tldraw store={...} />.

Directory layout

packages/sync/
├── package.json
└── src/
    ├── index.ts
    └── lib/
        ├── useSync.ts            # 19 KB hook
        ├── useSyncDemo.ts        # 10 KB demo hook
        └── useSyncDemo.test.ts

Key abstractions

Hook	Purpose
useSync({ uri, roomId, ... })	Connects to a TLSocketRoom over a WebSocket. Returns { store, status, error }.
useSyncDemo({ roomId })	Same, against tldraw's hosted demo server.

How it works

graph LR
    Component["<Tldraw store={syncedStore} />"] -->|store| Editor
    Component -->|hook| useSync
    useSync --> TLSyncClient
    TLSyncClient --> Adapter[ClientWebSocketAdapter]
    Adapter -->|wss://| Server[TLSocketRoom on Cloudflare]

useSync manages connection lifecycle, retries, presence injection, and asset upload via the configured asset store. The hook returns a status atom that the SDK uses to render the offline indicator and the error banner.

Integration points

• Imports. @tldraw/sync-core, @tldraw/store, @tldraw/tlschema, @tldraw/state, React.
• Importers. Templates that demonstrate multiplayer (templates/sync-cloudflare, templates/agent, templates/branching-chat, etc.) and the dotcom client (apps/dotcom/client).

Related

• @tldraw/sync-core
• Multiplayer sync feature