yjs-best-practices

Implement real-time collaborative editing with Yjs CRDTs, providers, and editor bindings.

1|Updated Jan 23, 2026
One-click install
npx skills add https://github.com/velt-js/agent-skills --skill yjs-best-practices-velt-js
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: yjs-best-practices
Source: https://github.com/velt-js/agent-skills/tree/main/skills/yjs-best-practices
Command: npx skills add https://github.com/velt-js/agent-skills --skill yjs-best-practices-velt-js

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Building real-time collaborative applications with Yjs involves subtle pitfalls — duplicate imports silently breaking sync, Y.Map tombstone growth, incorrect editor binding setup, and broken undo/redo — that cause data loss and hours of debugging. ## Core Features & Use Cases - Y.Doc Lifecycle Rules: Correct document creation, transaction batching with origin filtering, update encoding, state vector sync, and garbage collection configuration for version history. - Shared Types & Providers: Patterns for Y.Text, Y.Array, Y.Map, Y.XmlFragment, and YKeyValue, plus y-websocket, y-webrtc, and y-indexeddb provider setup. - Editor Bindings & Awareness: Integration guides for TipTap, ProseMirror, CodeMirror, Quill, and Monaco, with awareness protocol presence and Y.UndoManager patterns. - Use Case: Add collaborative editing to a Next.js app with TipTap and y-websocket — the skill provides the correct Collaboration extension setup, awareness cursor configuration, disabled built-in history, and cleanup on unmount. ## Quick Start Ask the agent to set up Yjs collaborative editing for your TipTap editor with y-websocket sync and cursor awareness.

Frequently Asked Questions about yjs-best-practices

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add collaborative editing to TipTap with Yjs?▼

Use TipTap's Collaboration extension configured with a Y.Doc and CollaborationCursor with your provider and user info. Disable StarterKit's built-in history since Yjs provides its own undo manager, and destroy the editor, provider, and Y.Doc on unmount.

Y.Map vs YKeyValue: which should I use for frequently updated keys?▼

Use YKeyValue from the y-utility package for frequently updated keys like cursors or counters. Y.Map retains every historical value as a CRDT tombstone, so 100,000 updates to one key can grow the document by hundreds of kilobytes.

Why are my Yjs changes not syncing between clients?▼

The most common cause is duplicate Yjs imports — two copies of yjs in node_modules break instanceof checks silently. Run npm ls yjs, pin a single version via package manager overrides, and verify both clients use the same room name and one Y.Doc per room.

Does Yjs support offline persistence in the browser?▼

Yes, y-indexeddb provides offline persistence by storing document updates in the browser's IndexedDB. Connect it to the same Y.Doc as your network provider so local state syncs when connectivity returns.

When should I disable garbage collection on a Y.Doc?▼

Set gc: false only when you need version history or time-travel via Y.snapshot, since disabled GC retains all deleted content metadata. The setting must be consistent across all peers, and UndoManager does not require it.

Should I use Yjs subdocuments for multiple editors?▼

Prefer a single Y.Doc with a Y.Map holding multiple Y.XmlFragment entries for multi-editor layouts — all fragments sync through one provider. Reserve subdocuments for genuinely large documents requiring lazy-loaded sections.