yjs-best-practices

Duplicate Yjs imports are fixed by forcing a single version through package manager resolutions. Add a resolutions field in package.json for npm or yarn, or pnpm overrides for pnpm, and configure bundler aliases so only one Yjs instance is bundled.

YKeyValue from the y-utility package is more efficient than Y.Map for frequently updated keys because document size depends only on map size, not operation history. Benchmarks show 100k operations on 10 keys shrinking from 524KB with Y.Map to 271 bytes with YKeyValue.

Use Yjs subdocuments only when you have multiple very large documents in the same room or need to lazy-load documents individually. For most cases, including multiple text editors on one page, a Y.Map organizing shared types is simpler and performs better.

Yjs documents grow because Y.Map retains all historical key values to resolve conflicts, and alternating updates to different keys break its optimization. Switching to YKeyValue from y-utility keeps document size proportional to the data, not the operation count.

Yjs experimental V2 encoding requires all connected clients to enable the same option, such as useV2Encoding_experimental in the Liveblocks Yjs provider. Clients with mismatched settings will not understand each other's changes.