Local models. Shared when you need them.

Start with a complete local model #

Create objects, organize their relationships, and observe changes. Collections, parent-child relationships, and MobX reactivity all work locally, without creating a document.

import { Plexus, PlexusModel, syncing } from "@here.build/plexus";

@syncing("Task")
class Task extends PlexusModel<Project> {
  @syncing accessor title = "";
  @syncing accessor done = false;
}

@syncing("Project")
class Project extends PlexusModel {
  @syncing.child.list accessor tasks!: Task[];
}

const project = new Project();
const task = new Task({ title: "Ship the editor" });

project.tasks.push(task); // task.parent === project, already locally
task.done = true;        // MobX observers see the change

Add a shared context #

When collaboration becomes part of the application, put that existing model into a document:

const plexus = Plexus.bootstrap(project);

plexus.root === project;      // The same project instance
project.tasks[0] === task;    // The same task instance
task.parent === project;    // The same relationship
task.uuid;                   // Now identifiable across environments

The document adds replicated state and cross-environment identity. A provider can now exchange that state with other clients. Your existing references and observers keep working, including when changes arrive from a peer.

This is progressive enhancement of the model: local objects are useful on their own, and document membership adds the capabilities that need a shared context. Follow the example from local to shared to watch that transition happen.

Useful locally, ready to share #

Where Plexus fits #

Your UI reads and writes Plexus models, and MobX tracks the fields it reads. When those models join a document, Yjs carries their replicated state. A provider exchanges updates between clients.

Use your existing Yjs infrastructure, or explore plexus-do for a Cloudflare Durable Object sync server. Connecting clients explains who creates the document and when a client can join.

Try it on a real application #

Why Plexus exists #

The usual CRDT tutorial works. A TodoMVC-grade app also works. Then a real application introduces related objects, document boundaries, providers, and persistence. Something does not sync, nothing throws, and days disappear.

A Carnegie Mellon user study examined the difficulties JavaScript developers encounter with collaborative data libraries. The discussion under a widely-read Yjs tutorial points to the same gap between a working demo and an application with a substantial data model.

Plexus lets a model grow from local use into collaboration. Classes, collections, relationships, and reactive reads already work in a local application. Joining a document enriches those same objects with replicated state and shared identity. Operations that violate ownership or document invariants throw explicit errors, keeping the model understandable as its context grows.