Local-first · Deterministic · Distributed state

Build collaborative systems
that converge

Build collaborative, offline-first, and distributed applications without designing your own synchronization, conflict resolution, replay, or replication layer. NodalMerge is a local-first distributed state engine: write locally, merge concurrently, converge deterministically, with full audit-grade replay semantics.

Get started →Explore the architecture Why NodalMerge

CRDT

State model

DAG

History structure

∞

Offline queue

P2P

Peer topology

Deterministic replayCanonical resolutionSpeculative writesAuthority policiesWebSocket-firstIndexedDB persistenceAudit-grade history

Real-world measurements

294,521 ops/sec

Native Rust core — real-world 259,778-edit editing trace, hash-linked DAG, per-character identity, policy checks all included.

119,482 ops/sec

Same engine, same trace, running in-browser via WASM — try it live in the Engine benchmark demo.

27,110 ops/sec

Same browser run, with an Ed25519 signature on every operation — the integrity work most CRDT libraries skip entirely.

See benchmarks/text-engine-performance for methodology, environment, and how to read these numbers safely.

How it works

One primitive does the work: immutable operations are what every peer stores and exchanges. Everything you actually read — canonical state, a registered query view, a speculative lane, even a materialization outside the state graph — is a programmable projection, a deterministic consequence of replaying that same history. See architecture/overview for the full layer breakdown and architecture/projections for why that consequence is the most underrated part of the design.

Choose your path

Frontend developer
Backend / operator
Platform team

You’re building a collaborative UI — real-time editing, presence, offline-first UX.

Install the SDK

npm install nodalmerge-sdk-js

Connect a room

const sdk = await createNodalMergeSdk({
  wsUrl: "ws://localhost:7878/ws/runtime",
  roomId: "my-room",
  transport: { mode: "auto" }, // SDK default is "ws-only"; "auto" adds WebRTC with WS fallback
  reconnect: { enabled: true }
});
await sdk.room.connect();

Read and write synced state

sdk.sync.set("profile/name", "Alice");
sdk.sync.push();
const name = sdk.sync.get("profile/name");

JavaScript SDK

Full API reference — sync, text, presence, blobs, offline, and config.

SDK overview

Pick the right surface, understand intent vs canonical patterns.

Subscriptions

Event subscriptions, runtime message types, lifecycle hooks.

Collab text playground

Interact with RGA text ops and DAG replay live.

You’re running or embedding the runtime — server setup, persistence, topology, auth.

Start the server

cargo run -p nodalmerge-server -- \
  --store ./data \
  --metrics-addr 127.0.0.1:9090

Verify health

curl http://127.0.0.1:9090/metrics

Server listens at ws://127.0.0.1:7878/ws/<room>.

Lock down auth

Set set-room-key with an Ed25519 key and configure set-policy rules before routing production traffic.

Server setup

Binary flags, storage options, and launch validation.

Persistence

SQLite node storage, blob backends, peer-local IndexedDB, and recovery.

Security and auth

Ed25519 room keys, JWT tokens, and policy rule wiring.

WebSocket commands

Full command/response contract including topology and archive ops.

Core capabilities

🔀

Deterministic CRDT merge

All peers converge to the same canonical state regardless of write order or network partitions.

📼

Replay-grade history DAG

Every change is a node in an append-only DAG. Replay any window, branch, or ancestor state on demand.

✈️

Full offline queue

Writes queue locally while disconnected and flush deterministically on reconnect — no data loss.

🏛️

Authority-scoped policies

Lock write authority to specific key paths and peers. Policy violations are rejected, not silently dropped.

🧵

RGA collaborative text

Character-level RGA with tombstone semantics, anchor-based positioning, and per-glyph attribution.

🔍

Canonical projections

Reference sections

Architecture

System model, CRDT behavior, replay semantics, speculative vs authoritative, and topology boundaries.

Protocol

Message-level sync, reconciliation flow, blob transfer, and failure semantics.

SDK

JavaScript and React integration — sync, text anchors, presence, offline, projections, and config.

API and commands

Full WebSocket command/response contract, capability gates, and rejection taxonomy.

Operators

Setup, persistence, GC lifecycle, observability, topology, and replay operations.

Benchmarks

Performance expectations and runtime attribution guidance.

Guides

Practical implementation guides for real product workflows.

Tutorials

Hands-on walkthroughs: protocol tracing, incident triage, replay inspection.

Developer experience apps

Five interactive playground apps

Workflow demo, collab text, protocol inspector, replay lab, and collab maps — local playgrounds for exercising SDK, replay, and protocol behavior live. See developer-experience/apps for what each app demonstrates and how to run them.

Suggested first hour

Run the quickstart

Start a local server and validate your first room end-to-end. → Quickstart

Follow the first-hour onboarding path

Validate SDK + WASM flows, inspect protocol behavior, check presence and replay evidence. → First hour path

Explore the interactive apps

Use the collab-text and protocol-inspector playgrounds to observe runtime behavior live. → Developer experience apps

Read the architecture fundamentals

Mental model + CRDT model are the highest-leverage reads before writing integration code. → Mental model · → CRDT model

Configure your production baseline

Server setup, persistence strategy, security posture. → Server setup · → Persistence

Introduction

NodalMerge

Build collaborative systems
that converge

JavaScript SDK

SDK overview

Subscriptions

Collab text playground

Server setup

Persistence

Security and auth

WebSocket commands

First hour path

First day builder path

Frontend app team path

Platform operator path

Architecture

Protocol

SDK

API and commands

Operators

Benchmarks

Guides

Tutorials

Five interactive playground apps

​Build collaborative systems that converge

JavaScript SDK

SDK overview

Subscriptions

Collab text playground

Server setup

Persistence

Security and auth

WebSocket commands

First hour path

First day builder path

Frontend app team path

Platform operator path

Architecture

Protocol

SDK

API and commands

Operators

Benchmarks

Guides

Tutorials

Five interactive playground apps

Build collaborative systems
that converge