Skip to content
Strata Sync

AI agents: fetch the documentation index at llms.txt. Markdown versions are available by appending .md to any page URL, including this page's markdown.

@stratasync/y-doc

Yjs CRDT integration for real-time collaborative editing in Strata Sync.

Manages Y.Doc instances for collaborative text editing, handles the Yjs sync protocol, and tracks presence per document.

What it provides

  • YjsDocumentManager: manages Y.Doc instances per entity field, handles sync protocol messages, tracks connection state, and derives text content from CRDT state
  • YjsPresenceManager: tracks viewing/editing presence per document, signals focus/blur to the server, and receives session state updates
  • Message types: typed client and server messages for the Yjs sync protocol, presence signaling, and error handling
  • Utility functions: DocumentKey serialization helpers and message type guards

Installation

npm install @stratasync/y-doc yjs

yjs is a peer dependency, so install it alongside @stratasync/y-doc.

Package exports

The root barrel re-exports the managers, persistence helpers, public types from types.ts, and the type guards.

import {
  YjsDocumentManager,
  YjsPresenceManager,
  clearPersistedYjsDocuments,
  createPersistedYjsPrefix,
  toDocumentKeyString,
  fromDocumentKeyString,
  isYjsSyncStep2Message,
  isYjsUpdateMessage,
  isSessionStateMessage,
  isLiveEditingErrorMessage,
} from "@stratasync/y-doc";

import type {
  ConnectOptions,
  DocumentConnectionState,
  DocumentKey,
  DocViewMessage,
  DocFocusMessage,
  LiveEditingErrorCode,
  LiveEditingErrorMessage,
  SessionParticipant,
  SessionState,
  YjsDocumentManagerConfig,
  YjsTransport,
  ClientMessage,
  ServerMessage,
  YjsTransportConnectionState,
  YjsSyncStep1Message,
  YjsSyncStep2Message,
  YjsUpdateMessage,
  YjsUpdateToServerMessage,
} from "@stratasync/y-doc";

Core concepts

DocumentKey

A triple identifying a collaborative field: entity type, entity ID, and field name.

interface DocumentKey {
  entityType: string; // Model name, such as "Task"
  entityId: string; // Model instance ID
  fieldName: string; // Field name, such as "description"
}

Use toDocumentKeyString and fromDocumentKeyString to convert between DocumentKey objects and their string form ("Task:abc-123:description").

Yjs sync protocol

Two-step sync:

  1. SyncStep1: the client sends its state vector to the server
  2. SyncStep2: the server responds with the diff (missing updates)
  3. Updates: after sync, incremental updates flow bidirectionally

All Yjs data is binary-encoded (Uint8Array) and transmitted as base64 strings within JSON messages.

Transport layer

Both managers need a YjsTransport to send and receive messages:

interface YjsTransport {
  send(message: ClientMessage): void;
  onMessage(callback: (message: ServerMessage) => void): () => void;
  isConnected(): boolean;
}

@stratasync/transport-graphql provides YjsTransportAdapter, which bridges the Yjs protocol over the existing WebSocket connection.

Architecture role

Sits between @stratasync/core and higher-level packages.

sync-core
  ^-- sync-y-doc
        ^-- sync-transport-graphql (provides YjsTransportAdapter)
        ^-- sync-react (useYjsDocument, useYjsPresence hooks)

Framework-agnostic: no React or browser dependencies beyond yjs.