skillctl install -r skillhub yjs-crdt

Yjs CRDT Domain Skill

This skill helps an agent design, implement, and debug collaborative features using Yjs with production-oriented defaults.

When to Use This Skill

Use this skill when tasks include any of the following:

• Real-time collaborative editing
• CRDT data modeling and conflict-free merge behavior
• Integrating Yjs providers (y-websocket, y-webrtc, custom provider)
• Awareness/cursor presence and shared selection
• Offline-first sync, incremental update sync, persistence, and replay
• Editor binding integration (ProseMirror, Tiptap, Monaco, CodeMirror, Quill)

What This Skill Provides

• Decision guidance for document model + network provider + persistence strategy
• Copy-ready API usage patterns for common Yjs operations
• A troubleshooting playbook for duplicate updates, loops, and state divergence
• A searchable local reference set under references/

Recommended Execution Flow

1. Clarify collaboration scope: text-only vs rich schema, single doc vs multi-doc workspace.
2. Select shared types and schema boundaries (Y.Map, Y.Array, Y.Text, nested types).
3. Choose transport provider and room strategy.
4. Implement initial sync using state vectors and incremental update propagation.
5. Add awareness (presence/cursors) separately from persisted content.
6. Add persistence/recovery strategy and compaction/GC policy.
7. Validate idempotency and out-of-order update safety.

Architecture Defaults

1) Data Model

• Put durable document data in Yjs shared types.
• Keep ephemeral UI state (selection, cursors, online status) in provider awareness.
• Use stable keys in top-level Y.Map for evolvable schemas.

2) Sync Strategy

• Initial: exchange state vector and send only missing updates.
• Ongoing: subscribe to ydoc.on('update', ...) and broadcast binary updates.
• Persistence: append binary updates, periodically compact via merged snapshots.

3) Provider Strategy

• Start with y-websocket for server-backed rooms.
• Use y-webrtc for peer-first/low-infra setups.
• Implement custom provider when integrating existing infra/queue/storage.

Copy-Ready API Patterns

Basic document + shared types

import * as Y from "yjs";

const ydoc = new Y.Doc();
const ymeta = ydoc.getMap("meta");
const ytext = ydoc.getText("content");

ymeta.set("title", "Untitled");
ytext.insert(0, "Hello collaborative world");

Incremental update replication

import * as Y from "yjs";

const docA = new Y.Doc();
const docB = new Y.Doc();

docA.on("update", (update) => Y.applyUpdate(docB, update));
docB.on("update", (update) => Y.applyUpdate(docA, update));

Efficient initial sync using state vector

import * as Y from "yjs";

const svA = Y.encodeStateVector(docA);
const svB = Y.encodeStateVector(docB);

const diffToB = Y.encodeStateAsUpdate(docA, svB);
const diffToA = Y.encodeStateAsUpdate(docB, svA);

Y.applyUpdate(docB, diffToB);
Y.applyUpdate(docA, diffToA);

Origin-based loop prevention in custom providers

import * as Y from "yjs";

class BridgeProvider {
  constructor(private ydoc: Y.Doc) {
    this.ydoc.on("update", (update, origin) => {
      if (origin === this) return;
      this.sendToNetwork(update);
    });
  }

  onRemoteUpdate(update: Uint8Array) {
    Y.applyUpdate(this.ydoc, update, this);
  }

  sendToNetwork(update: Uint8Array) {
    // transport-specific implementation
  }
}

Edge Cases and Diagnostics

• Feedback loop / duplicate packets: ensure transaction origin is set and filtered.
• Large update logs: merge updates and periodically rebuild compact state.
• JSON transport constraints: encode binary updates as Base64 only when needed.
• Divergence suspicion: compare state vectors and re-diff updates.
• Undo/redo confusion: scope undo manager per editor binding and user intent.

Deliverable Checklist (for agents)

• Data model and key schema documented
• Provider + room naming strategy selected
• Initial sync + incremental sync paths implemented
• Awareness channel integrated (not persisted as document data)
• Persistence and replay plan defined
• Failure/reconnect behavior verified

Local Reference Index

Use local resources for fast retrieval:

• references/README.md
• references/source-index.json
• references/official-demos.md
• references/api-quick-reference.md

Source Provenance

This skill is aligned with public official sources from Yjs docs and official repositories.