July 31, 2026

Yjs solves sync. It doesn't solve your app.

Figma famously built its own multiplayer engine. We deliberately didn't — and this is a tour of everything we had to build anyway to make one CRDT drive a 60fps canvas, a React panel tree, and a fleet of headless Lambdas.

Christoph Schütte

In 2019, Figma published How Figma's multiplayer technology works, and it opens with a flex that has aged into a classic: nothing off the shelf could do what they needed, so they built their own multiplayer engine — client, server, conflict resolution, the works.

It's one of our favorite engineering posts. And when we built the collaborative timeline behind Solid's video editor, we did the exact opposite.

Not because the problem got easier. Because the problem *moved*. In 2019, making N replicas of a document agree was a research-grade problem. In 2026 it's a library: Yjs gives you a CRDT that converges, and Liveblocks hosts the rooms and the WebSockets. Building your own sync engine today is like building your own database — there's a version of the story where it's justified, and there's the version that's much more common.

So we did the boring thing. And here's what the boring thing actually buys you: a document that converges, and an event that fires when it changes.

That's it. That's the whole contract.

Between that event and a video editor — a PixiJS canvas repainting at 60fps, panels full of React components, an undo stack, twenty-seven schema versions, servers that need to read the same document with no browser in sight — there is a lot of software. Nobody ships that part, because that part *is* your app.

This post is a tour of ours.

One document, three very different readers

A timeline document at Solid holds everything about an ad being edited: segments, tracks, clips, transitions, caption styling, audio effects. Several people can have it open at once, and every one of their edits is a CRDT delta applied to a shared Y.Doc.

The interesting tension isn't the writers. It's the readers:

  • React panels — properties, track headers, the transcript. Declarative, and allergic to unnecessary re-renders.
  • The canvas — an imperative PixiJS scene graph that repaints on a clock. It doesn't want a virtual DOM diff; it wants to know *precisely which texture is stale*.
  • Headless servers — Lambdas that hydrate the document with no browser, no React, and no canvas, to serialize, validate, and persist it. (More on that at the end — it's the best part.)

Yjs answers all three the same way: "the document changed." Cool. *Which part?* A naive integration subscribes to the doc and re-derives everything — fine for a form, death for a timeline where a collaborator dragging one volume slider emits dozens of deltas per second.

What we wanted is a single reactive vocabulary that all three readers already speak. For us that's MobX: React components subscribe through observer(), the canvas subscribes through autorun, and plain server code just reads values and ignores the reactivity entirely. The whole problem reduces to one question:

How do you turn CRDT deltas into MobX invalidations that are exactly as fine-grained as the edits?

We ended up with Figma's document, one layer down

Figma models its document as a tree that syncs like a map: Map<ObjectID, Map<Property, Value>>, with each object's parent stored *as a property of the child*. When we designed our document we started from our own constraints — and converged on the same shape. It's a good shape.

A composition's Y.Doc contains three top-level maps:

Y.Doc
├── nodes:          Y.Map  nodeId  → [ {key, val}, {key, val}, … ]   // one entry per attribute
├── metadata:       Y.Map  version, aspectRatio, volume, …
└── relationships:  Y.Map  childId → "parentId\0parentType"

Every segment, track, clip, transition, and caption-style node is an entry in nodes: a bag of attributes keyed by name. (Why the attribute bag is an *array* of {key, val} pairs and not a nested Y.Map is its own section — hold that thought.)

The tree structure lives entirely in relationships, and the parent link is stored on the child:

// packages/composition-nodes/src/relationship-map.ts
// Y.Map 'relationships': childId -> "parentId\0parentType"
setParent(childId: string, parentId: string, parentType: string): void {
  this.yjsMap.set(childId, this.encode(parentId, parentType));
}

This is the same call Figma made, for the same reason: a child has exactly one relationships entry, so two collaborators concurrently moving the same clip is just two writes to the same key. Last writer wins, every replica agrees, and a node can never end up in two places at once — the failure mode you get if parents store lists of children.

Storing parents on children makes "give me all clips of this track" a scan, so on top of the raw map we keep a reactive reverse index: (parentId, parentType) → Set<childId>, rebuilt incrementally from map events, with a MobX atom per parent key. Children lookups are O(1), and adding a clip to a track invalidates exactly the observers of *that track's* clip list.

Sibling order is the one place we diverge from Figma. They interleave concurrently-inserted children with fractional indexing; we store an order attribute on each child and sort siblings on read. Concurrent reorders resolve as last-writer-wins on that attribute — cruder, but a timeline isn't a canvas: our trees are shallow, sibling counts are small, and "the later drag wins" is what a video editor should do anyway. We also get to skip Figma's whole reparenting-cycle saga, because our hierarchy is typed — clips go in tracks, tracks in segments, and no edit can express a clip adopting its own track.

One atom per attribute

Here's the heart of the bridge. MobX's primitive is the atom: a little subscription pebble with two methods. reportObserved() — called while some reactive computation is running — registers that computation as a dependent. reportChanged() invalidates every dependent. Everything else in MobX is built on this.

Our rule: one atom per node attribute, created lazily on first read.

// packages/core/src/yjs/observed-key-value.ts
get: (key: string) => {
  this.reportKeyObserved(key); // lazily creates the atom for `key`
  return cache.get(key)?.val;
},

private reportKeyObserved(key: string) {
  let atom = this.atoms.get(key);
  if (!atom) {
    atom = createAtom(key);
    this.atoms.set(key, atom);
  }
  atom.reportObserved();
}

On the other side, the Yjs event handler works out which keys a delta actually touched and calls reportChanged() on those atoms only.

Now trace a remote edit end to end. A collaborator drags a clip's volume slider. Their client writes volume into that clip's attribute store; a delta arrives in your tab; the handler resolves it to one changed key; one atom fires. The properties panel showing that slider re-renders. The waveform view whose autorun read volume re-runs. And *nothing else in the editor does any work at all* — not the timeline, not the neighboring clips, not even observers of the same clip's other attributes.

A remote edit to volume invalidates only the observers of volume. Every other atom stays asleep.
A remote edit to volume invalidates only the observers of volume. Every other atom stays asleep.

The consumers never learn any of this. A React panel calls clip.volume; the canvas subscribes by simply reading whatever it needs inside an autorun:

// packages/video-editor/src/views/composition/text-clip.view.ts
this.cancelRender = autorun(() => {
  const { fontFamily } = this.clip.style;

  if (this.fonts.isLoaded(fontFamily)) {
    this.renderText(); // reads text, layout, style — subscribing by reading
    this.requestRepaint();
  }
});

That autorun re-runs when — and only when — an attribute it read last time changes, whether the edit came from this tab, another tab, or another person on another continent. The view doesn't know Yjs exists. The document doesn't know PixiJS exists. MobX's dependency tracking is the only thing that knows both, and it rebuilds the wiring from scratch on every run.

The seam is invisible until it isn't. There's a comment at the top of the node base class that is a survivor of everyone's first week with it:

// packages/composition-nodes/src/base-node.ts
///
/// IF you are getting errors thrown from this file, don't forget to wrap your
/// clip or track creation in a MobX action!
///
Remember: match reactivity granularity to edit granularity. A collaborative edit is one attribute, so one attribute is one atom. Any coarser and remote edits trigger work they didn't cause; any finer and you're inventing structure the document doesn't have.

The key-value store that's secretly an array

Look back at the document shape and you'll notice something odd: a node's attributes aren't a nested Y.Map. They're a Y.Array of {key, val} pairs.

They *were* a Y.Map, originally. The problem is a CRDT-shaped one: to resolve conflicts among concurrent writers, a Y.Map retains tombstone metadata for every write ever made to a key. Write the same key ten times, and the document remembers ten writes, forever. Yjs's own y-utility benchmarks make the point brutally — same workload, 100,000 writes:

workloadas Y.Mapas array-backed KV
100k writes, 10 keys~525 KB271 bytes
500k writes, 1k keys~3 MB~31 KB

Now remember what an editor does: a volume slider drag is *hundreds of writes to one key*. On a Y.Map, every drag permanently fattens a document that we sync, snapshot, and re-load for years. On the array formulation, the document's size depends on the size of the map — not on the number of edits it took to get there.

The trick (it's the YKeyValue algorithm, from y-utility) is to store entries as array items and make writes append-only:

// packages/core/src/yjs/observed-key-value.ts
set: (key: string, value: T) => {
  doc.transact(() => {
    deleteEntry(array, key); // delete the current entry for the key
    array.push([{ key, val: value }]); // append the new one at the end
  });
},

Deleted array items compact away; the live entry is whichever one is rightmost. We inlined the algorithm rather than depending on y-utility, for two reasons the file states plainly: it drops an external dependency, and it lets the handler report straight into per-key MobX atoms instead of going through an intermediate event emitter. (The plain Y.Maps you saw earlier — metadata, the node registry, relationships — keep the simple observer. Those keys are written occasionally, not dragged.)

But appending-to-set opens a genuinely fun failure mode. Two collaborators set the *same key at the same time*. Both deltas are appends; both survive convergence. The array now honestly contains two entries for volume — the CRDT converged perfectly, to a state with a duplicate in it.

Here's the resolution, and it's the most CRDT-brained code in the codebase: every client deletes the losers, and they all delete the same ones. When the handler processes an event, the rightmost entry for a key becomes canonical, and any other entry for that key is deleted — inside a transaction, as a real Yjs operation. Every replica sees the same converged array, runs the same rule, and issues the *same deletions*. Deleting an already-deleted item is a no-op, so the fixups themselves converge, and a moment later every replica holds a one-entry-per-key array again.

Two concurrent writes to the same key both survive convergence — then every client deletes the same loser, deterministically.
Two concurrent writes to the same key both survive convergence — then every client deletes the same loser, deterministically.

Which entry ends up rightmost is arbitrary — Yjs orders concurrent inserts deterministically, and that's all we need. Figma's post said it about last-writer-wins and it's just as true here: it doesn't much matter who wins, as long as everyone agrees.

Remember: convergence plus a deterministic local rule is a distributed decision with no coordinator. If every replica computes the same fix from the same state, the fix is free to apply anywhere.

Undo is six lines and one number

Multiplayer undo is one of the hardest sections of Figma's post: undoing *your* edit without reverting everyone else's, redo across interleaved histories, the principle that undo-copy-redo shouldn't move the document. Real, subtle problems.

Our entire implementation:

// packages/composition-nodes/src/composition.ts
this.undoManager = new Y.UndoManager(this.document, {
  captureTimeout: 100,
});

Y.UndoManager scopes undo to locally-originated operations out of the box — collaborators' edits are untouched when you hit ⌘Z. The one decision left to us is captureTimeout: 100: operations within 100ms of each other merge into one undo step, so a slider drag is a single undo, not two hundred. We are not going to pretend there's a lesson here beyond the obvious one — this is what standing on a library is *for*. We got Figma's hardest section for the price of a constant.

The CRDT is a cache

Now the part where we get opinionated. Ask a collaborative-software person where the truth lives and they'll point at the CRDT — it's the thing being edited, the thing that converges, the thing everyone shares. Treat it as sacred.

Ours is disposable, and that's the best decision in the system.

The pressure that forces this is schema evolution. Our composition schema is twenty-seven versions deep — a chain of Zod schemas with a migrate() function that walks any historical composition JSON up to v27, one version at a time. Add captions-per-segment, restructure audio effects, split a field — every shape the product has ever saved still loads.

You cannot do that to a live CRDT. A Yjs document isn't a value; it's a history. There's no moment when a migration can atomically rewrite it — old clients may still be writing the old shape into the very same document while you do — and even if you pulled it off, the document permanently carries the structural bones of both shapes. Migrating a CRDT in place is how you end up supporting every version at once, forever.

So we never migrate the document. We version it — on two axes — and throw it away on mismatch:

// packages/composition-nodes/src/version.ts
export const YjsLayoutVersion = 5;

// Yjs documents are re-created from the database when this changes.
export const YjsDocVersion = `${LatestSchema.VersionIdentifier}.${YjsLayoutVersion}`; // "27.5"

The schema axis moves when the composition's *content* changes shape; the layout axis moves when we change how composition-nodes arranges that content inside Yjs (the Y.Map-to-array move from two sections ago was exactly such a bump — no schema change, new layout). Either way, when the editor opens a room, the check is blunt:

// apps/web/…/hooks/use-synchronized-editor.ts
const needsSeeding =
  yjsDoc.getMap('nodes').size === 0 ||
  yjsDoc.getMap('metadata').get('version') !== YjsDocVersion;

entry.editor = needsSeeding
  ? new EditorState({ composition: migrate(await fetchComposition()), yjsDoc, trackEvent })
  : new EditorState({ yjsDoc, trackEvent });

Version matches: attach, edit, done. Version doesn't match: fetch the composition JSON from the database, run it through the 27-step migration chain, and seed a *fresh* document. The old CRDT — with its history, its tombstones, its obsolete layout — is simply abandoned.

Which raises the obvious question: if the CRDT is disposable, what keeps the database copy fresh? A write-back loop. Every document update fires a webhook, and a Lambda hydrates the document — using the *same* Composition class the browser uses, headless, no React, no canvas, the MobX bridge idling harmlessly — serializes it with toJSON(), validates the result against the schema, and writes it to the database (queueing a thumbnail re-render while it's there):

// apps/liveblocks-webhook-receiver/…/ydoc-handler.service.ts
const composition = new Composition({ yjsDoc });

// If the Yjs document version doesn't match, ignore the event.
// This can happen when clients are running different versions of the app.
if (composition.version !== YjsDocVersion) {
  return;
}

const validated = parseComposition(composition.toJSON());
await this.databaseService.videoProjectRepository.update(videoProjectId, {
  composition: validated,
});

That version guard is the whole story in miniature: during a deploy, clients on different app versions coexist, and the receiver refuses to persist any document that doesn't match *its* version. The database only ever holds validated, schema-current JSON. The migratable golden copy lives in Mongo; the CRDT is a convergent, collaborative, *disposable* cache in front of it.

The lifecycle: version match attaches, mismatch reseeds from migrated JSON — and every update writes validated JSON back.
The lifecycle: version match attaches, mismatch reseeds from migrated JSON — and every update writes validated JSON back.

Disposability also quietly underwrites decisions that would otherwise be reckless. Node types are stored in the document as a numeric enum — insert a member in the middle and every persisted number after it silently means something else. That's a horrifying property for a durable format and a fine one for a cache with a version stamp: the same PR renumbering the enum bumps the version, every document gets rebuilt on next open, and no old number is ever reinterpreted. We get to make that class of change *at all* because no Yjs document outlives its format.

Remember: version the container separately from the content, and make the container the thing you can afford to throw away. A CRDT you can regenerate is infrastructure; a CRDT you must migrate is a liability with a conflict-resolution strategy.

The work moved up the stack

Figma's post closes by saying you now have enough information to build your own collaborative tree data structure. Seven years on, the honest update is: you don't have to, and mostly shouldn't. Convergence is a solved problem you can install.

What you can't install is the part where one converging document drives everything you've built — a canvas that must repaint in sixteen milliseconds, panels that must not re-render, servers that must read the same classes with no DOM, schemas that must keep evolving under live collaborators. The sync engine stopped being the moat and became the foundation. The bridge is where the engineering went.

If there's one thing to steal from this post, steal the shape of the decision: pick the boring sync engine, then spend every hour it saved you at the exact altitude where your product actually lives. For us that was an atom per attribute, a key-value store that's secretly an array, and the nerve to treat a CRDT like a cache.

Solid is an AI video editor. If "one atom per attribute" is the kind of hill you'd happily die on, we're hiring.

Latest posts
How Fast-Growing Brands Source Video ContentInsights · November 19, 2026Supplement Ads 2026: Rules, Angles, AI WorkflowInsights · November 19, 2026How to Build a Creative Engine With a Lean Marketing TeamInsights · November 18, 2026AI Tools for Marketers in 2026: The Stack by JobInsights · November 18, 2026Pet Food Advertising: How Brands Scale Video Ads With AIInsights · November 18, 2026