Sync
crdt_socket_sync sends each
change to the other peers as it happens, over WebSocket. A peer that was offline
catches up when it reconnects, and a client that cannot keep up is dropped and
re-syncs. It comes with reconnection, liveness checks, history pruning, a
version handshake and plugins (such as awareness, for remote cursors).
dart pub add crdt_socket_sync
It plugs into your server
You do not need a dedicated sync server. The sync protocol runs inside the backend framework you already use:
| Framework | Package |
|---|---|
| Dart Frog | crdt_socket_sync_dart_frog: handlers ready to return from a route |
| Serverpod | crdt_socket_sync_serverpod: web routes ready to add to your pod |
plain dart:io | WebSocketServer / WebSocketRelayServer, included in crdt_socket_sync |
| anything else | a transport of your own, or a relay in any language |
Your authentication, routing and deployment stay the framework's. The
server frameworks page shows both, side by side. The
client is the same whatever the server: a WebSocketClient or a
WebSocketRelayClient, usually opened through a replica.
Two modes
The package has two independent sync models. The only fundamental difference is where the CRDT logic lives:
| Server–client | Relay | |
|---|---|---|
| The server | understands crdt_lf: holds the documents, applies and merges changes | stores and rebroadcasts opaque change blobs; never parses CRDT data |
| Merging | on the server and on the clients | on the clients only |
| History pruning | the server takes a snapshot once every client is aligned | the relay asks one client to upload a snapshot |
| Server code | Dart, with crdt_lf | any runtime: Dart, a Cloudflare Worker in TypeScript, … |
| Pick it when | one authoritative backend should understand the documents | you want a cheap, CRDT-agnostic backend, easy to port and to scale |
Everything else (delivery guarantees, reconnect policy, initial sync) follows from that choice.

How this section is organized
Pick a mode with the table above, then read its group and the shared one. You can skip the group of the other mode.
Server–client mode
A server that holds the documents and merges the changes.
- Server–client mode: quick start, how the handshake and the pruning work, the server events.
- Server registry: where the server keeps its documents, in memory or on disk with any storage adapter.
- Examples: a persistent server with the awareness plugin, and its Flutter client, with the same screens as the Flutter examples. The repository has VS Code launch settings to run both.
Relay mode
A server that stores and forwards opaque blobs. The clients do all the merging.
- Relay mode: quick start, join and push, log compaction, and how Greyhound Markdown uses it.
- Relay protocol: the JSON contract, to write a relay on any runtime.
- Example: Greyhound Markdown syncs through a relay, live and on your machine. The live app talks to a Cloudflare Worker written in TypeScript. Locally, the same client talks to a Dart Frog or Serverpod relay from the repository: see Greyhound Markdown on a relay.
Both modes
What both modes share lists the pages that apply to either mode:
- Server frameworks: Dart Frog and Serverpod, one section per mode.
- Plugins and awareness, connection and errors, versions and compatibility, compression and custom transport.
- Open a replica: the client side of an app, with either client.
Imports
One library per side and per mode:
// Both modes. CRDTReplica: the document, its local storage and its client
import 'package:crdt_socket_sync/replica.dart';
// Server–client mode
import 'package:crdt_socket_sync/client.dart'; // client interfaces
import 'package:crdt_socket_sync/web_socket_client.dart'; // WebSocket client
import 'package:crdt_socket_sync/server.dart'; // server interfaces, DocumentSessionHost (no dart:io)
import 'package:crdt_socket_sync/web_socket_server.dart'; // WebSocket server (dart:io)
// Relay mode
import 'package:crdt_socket_sync/relay_client.dart'; // relay client interfaces
import 'package:crdt_socket_sync/web_socket_relay_client.dart'; // WebSocket relay client
import 'package:crdt_socket_sync/relay_server.dart'; // RelayStore, RelaySessionHost (no dart:io)
import 'package:crdt_socket_sync/web_socket_relay_server.dart'; // WebSocket relay server (dart:io)
Runnable Dart Frog and Serverpod servers, one per mode, are listed in Server frameworks.