vectis-crdt

01Overview

vectis-crdt is an open-source (MIT, v0.2.0) conflict-free replicated data type for the browser. It implements an RGA/YATA ordered sequence with per-object LWW registers, compiled from Rust to WebAssembly (wasm32-unknown-unknown). Every peer edits locally without coordination; deltas are exchanged as compact binary patches, and a deterministic merge engine guarantees that all peers converge to the same state — regardless of the order in which operations arrive.

Conflict-free by construction. Zero backend for merge logic.

Built for collaborative edges

02How it works

Three steps, no conflicts:

1. EDIT — produce an operation locally. insert(pos, obj) → RGA/YATA: a local op, no coordination with other peers.
2. SYNC — exchange deltas with peers. doc.delta() → binary bytes: only the changed ops travel, keeping the wire minimal.
3. CONVERGE — deterministic merge, no conflicts. peer.apply(delta) → same state: the vector clock enforces causal order.

Runtime topology

Every edit flows through seven stages, in one pass:

Operation → RGA/YATA → LWW Reg → Vector Clock → Delta Sync → Merge Engine → State

The four merge stages

Four stages, one pass — each with a bounded cost:

Core CRDT ideas

RGA/YATA — the ordered sequence

The document body is a Replicated Growable Array using the YATA variant of the algorithm. Inserts and deletes are appended to a log; deleted items are tombstoned in the RGA log rather than removed, which is what guarantees convergence when a delete races a concurrent operation on the same element.

LWW registers — mutable properties

Each object in the sequence carries per-property Last-Write-Wins registers (color, width, opacity, transform — any mutable property). When two peers write the same property concurrently, the write with the later timestamp wins on every peer, deterministically.

Vector clocks — causality

A vector clock tracks the causal ordering of operations across peers. It is what lets a peer work offline and, on reconnect, exchange exactly the operations the other side has not seen. Clock comparison costs O(peers).

Convergence

The merge engine is deterministic: given the same set of operations, in any delivery order, every replica computes the identical final state. There is no conflict-resolution callback, no server-side arbitration — zero backend for merge logic.

03Install

vectis-crdt ships as an npm package wrapping the WebAssembly build, and as a Rust crate.

npm install vectis-crdt
# or
pnpm add vectis-crdt
yarn add vectis-crdt

cargo add vectis-crdt

04Quick start

Up in under a minute: create a document, insert two shapes, export a delta, and apply it on a second peer.

import { VectisDoc } from "vectis-crdt";

const doc = await VectisDoc.create();

doc.insert(0, { id: "shape-1", color: "#c0432c", width: 2 });
doc.insert(1, { id: "shape-2", color: "#2e4a6b", width: 1 });

const delta = doc.delta();

const peer = await VectisDoc.create();
peer.apply(delta);

console.log(peer.state());

05API reference

vectis-crdt exposes a single class, VectisDoc, that wraps the WebAssembly CRDT engine. All merge logic runs in the WASM sandbox; the JS surface is thin and synchronous.

Document operations at a glance

Methods

import { VectisDoc } from "vectis-crdt";

const doc = await VectisDoc.create();
console.log("VectisDoc ready");

doc.insert(0, { id: "shape-1", color: "#c0432c", width: 2 });
doc.insert(1, { id: "shape-2", color: "#2e4a6b", width: 1 });

doc.delete("shape-1");

doc.setProp("shape-1", "color", "#00f");
doc.setProp("shape-1", "width", 4);

const bytes = doc.delta();
// send bytes over WebSocket, WebRTC, etc.
ws.send(bytes);

ws.onmessage = (e) => {
  doc.apply(new Uint8Array(e.data));
  render(doc.state());
};

06Delta sync & wire format

vectis-crdt never ships full documents over the network. doc.delta() exports only the operations produced since the last export, as a compact binary patch (Uint8Array) — the transport is yours: WebSocket, WebRTC, or anything that moves bytes.

• Delta-only — only changed ops travel; the wire stays minimal.
• Binary encoding — the changeset is binary-encoded, not JSON, keeping bandwidth minimal.
• Op kinds — a delta carries ins (insert), del (delete), prop (LWW write), and ack entries, together with the sender's vector clock.
• New peers — a peer that has never synced simply receives the full log as its first delta; from then on, exchanges are incremental.
• Idempotent, order-tolerant merge — doc.apply() uses the vector clock to place remote ops in causal order, so deltas can arrive late, duplicated, or interleaved and every replica still converges.

07Guides & recipes

Get vectis-crdt running in minutes — from a two-peer offline merge to a live multi-peer canvas.

Basic two-peer example

This example shows two peers editing the same document offline and converging on reconnect.

import { VectisDoc } from 'vectis-crdt';

const alice = await VectisDoc.create('alice');
const bob   = await VectisDoc.create('bob');

// Both insert elements concurrently (offline)
const opA = alice.insert('circle-1', { after: 'root' });
const opB = bob.insert('rect-1', { after: 'root' });

// Set properties
const opAColor = alice.setProp('circle-1', 'color', '#c0432c');
const opBColor = bob.setProp('rect-1', 'color', '#2e4a6b');

// Reconnect — exchange all ops
alice.apply(opB);
alice.apply(opBColor);
bob.apply(opA);
bob.apply(opAColor);

// Both converge to identical state
console.log(alice.toArray()); // same order on both peers
console.log(bob.toArray());   // identical

WebSocket integration

Connect multiple browser peers via WebSocket for real-time collaboration.

import { VectisDoc } from 'vectis-crdt';

const peerId = crypto.randomUUID();
const doc = await VectisDoc.create(peerId);
const ws = new WebSocket('wss://your-relay.example.com');

// On connect, send our current state as delta
ws.onopen = () => {
  const delta = doc.delta(); // full log for new peers
  ws.send(JSON.stringify({ type: 'sync', ops: Array.from(delta.ops) }));
};

// Apply remote ops
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type === 'op') doc.apply(msg.op);
  if (msg.type === 'sync') doc.applyDelta({
    ops: new Uint8Array(msg.ops),
    clock: msg.clock
  });
};

// Local insert — broadcast to all peers
function addShape(id, afterId) {
  const op = doc.insert(id, { after: afterId });
  ws.send(JSON.stringify({ type: 'op', op }));
  render(doc.toArray());
}

React example

import { useEffect, useState } from 'react';
import { VectisDoc } from 'vectis-crdt';

export function CollabCanvas() {
  const [doc, setDoc] = useState(null);
  const [elements, setElements] = useState([]);

  useEffect(() => {
    VectisDoc.create('peer-' + Date.now()).then(d => {
      setDoc(d);
      setElements(d.toArray());
    });
  }, []);

  function addCircle() {
    const id = 'circle-' + Date.now();
    doc.insert(id, { after: 'root' });
    doc.setProp(id, 'color', '#c0432c');
    setElements([...doc.toArray()]);
  }

  return (
    <div>
      <button onClick={addCircle}>Add circle</button>
      <ul>{elements.map(id => <li key={id}>{id}</li>)}</ul>
    </div>
  );
}

08Capacity & default limits

The defaults are tuned for collaborative canvases in the browser:

© 2026 VectisCRDT contributors · MIT · Built with Rust → wasm32-unknown-unknown.