y-protocols

y-protocols implements the wire-format protocols used by Yjs network providers, giving library authors the low-level building blocks to add real-time collaboration transport to a custom backend (WebSocket server, WebRTC signaling, or otherwise) without reimplementing Yjs’s binary encoding from scratch. It’s organized into three focused modules: sync for reconciling a Yjs document’s state between two peers via a state-vector handshake (writeSyncStep1/writeSyncStep2) and update propagation, awareness for maintaining and broadcasting ephemeral per-client presence state (cursor position, username, color) with automatic timeout-based cleanup of stale clients, and auth for encoding authorization/permission errors over the wire.

Because these protocols are decoupled from any specific transport, they underpin most of the Yjs provider ecosystem (y-websocket, y-webrtc, and others), each of which just needs to move the encoded bytes across its chosen transport and call into y-protocols to interpret and apply them. This makes the package most relevant to developers building or maintaining a Yjs network provider rather than end-application developers, who typically depend on it only transitively through an existing provider package.

What You Get

• A sync module (writeSyncStep1/writeSyncStep2/writeUpdate/readSyncMessage) implementing the state-vector handshake used to reconcile two Yjs document replicas
• An awareness module for maintaining and broadcasting ephemeral per-client state (presence, cursor position, username/color)
• Automatic timeout-based cleanup of awareness state for clients that stop refreshing it (default 30s)
• An auth module for encoding authorization/permission-denied errors over the same binary wire format
• A documented protocol spec (PROTOCOL.md) describing the exact byte-level message formats independent of the JS implementation
• Transport-agnostic design so the same protocol logic works across WebSocket, WebRTC, or any custom transport

Common Use Cases

• Building a custom Yjs network provider for a transport not covered by existing providers (e.g. a proprietary message bus)
• Implementing a Yjs-compatible collaboration server that needs to speak the same sync protocol as y-websocket
• Adding cursor/presence indicators to a collaborative editor via the awareness protocol
• Debugging or extending an existing Yjs provider by working directly with the underlying sync/awareness wire formats

Under The Hood

Architecture - The package is split into three small, independent modules (src/sync.js, src/awareness.js, src/auth.js) each handling one protocol concern; sync.js implements the state-vector-based handshake (SyncStep1/SyncStep2) for reconciling Yjs document replicas, while awareness.js maintains a shared Map<clientID, state> with a local timeout sweep that drops clients whose state hasn’t refreshed recently. All modules build directly on lib0’s encoding/decoding primitives rather than a general-purpose serialization format, keeping the wire format compact and specific to Yjs’s needs. Tech Stack - Plain JavaScript (ES modules) with TypeScript type declarations generated via tsc --skipLibCheck from JSDoc annotations rather than hand-written .ts source; standard is used for linting and lib0 is the only meaningful runtime dependency. Code Quality - The module surface is intentionally small (under 600 lines across the three protocol files), and awareness behavior is covered by awareness.test.js; the project also maintains a separate PROTOCOL.md document specifying the exact byte-level message layout, which serves as a language-agnostic reference for reimplementing the protocol outside JavaScript. API Design - The API mirrors Yjs’s own encoder/decoder conventions (encoding.createEncoder(), decoding.createDecoder(buffer)), so developers already familiar with lib0/Yjs internals can pick it up quickly, but the protocol-level API (state vectors, sync steps, awareness timeouts) assumes real familiarity with CRDT sync mechanics rather than being a beginner-friendly high-level API.