ShareDB: A JSON OT Backend for Multi-User Editing

What ShareDB Is For, and Who Ends Up Using It

ShareDB is described in its README as "a realtime database backend based on Operational Transformation (OT) of JSON documents," and as "the realtime backend for the DerbyJS web application framework." That second sentence explains the project's shape. It is not a standalone product with a UI; it is the server-side engine that lets several clients edit the same JSON document at once and converge on the same result.

The problem it addresses is concurrent editing. If two users change different fields of the same object at the same time, last-write-wins loses one of the changes. OT solves this by representing each edit as an operation, transforming operations against each other so they can be applied in any order and still produce the same document. ShareDB does that transformation for JSON, which is a harder target than plain text because operations can insert, delete and move values at arbitrary paths.

The audience follows from the feature list: teams building collaborative editors, shared forms, dashboards or any app where a document is open in more than one place. The README also lists "In-memory implementations of database and pub/sub for unit testing," which tells you the intended users are application developers writing tests around their own sync logic, not people looking for a hosted service.

How the OT Pipeline Works Between Client and Store

The mechanism visible in the repository is a layered one. The lib/ directory holds the core, package.json names ot-json0 as the only OT type in dependencies, and the README lists the surrounding capabilities: realtime query subscriptions, projections, middleware, historic document versions and presence syncing.

An edit starts as an operation against a document at a known version. The client submits it; the server validates it, transforms it against any operations that arrived first, applies it, and commits a new version. Because the server stores operations rather than only the final document, the README can list "Access to historic document versions" as a feature. That is the trade-off of OT versus state-based sync: you keep an operation log, and the log is what lets a reconnecting client catch up.

Scaling is handled by pushing the fan-out problem to pub/sub. The README states "Horizontally scalable with pub/sub integration," which means multiple ShareDB server processes coordinate through an external message bus rather than through shared memory. The database adapter is likewise pluggable, described as "Simple integration with any database." Neither the database nor the pub/sub is in the dependency list, so both are things you choose and wire up. Middleware is the extension point for access control and custom behavior, and projections let you expose only selected fields from documents and operations.

Installing ShareDB and Submitting a First Operation

The README documents the package on npm and points to https://share.github.io/sharedb/ for the full documentation. The repository does not include a quick-start snippet in the README itself, so the commands below are limited to what package.json and the README state: the package name, the version, and the development scripts.

Install the package from npm. The published name is sharedb, and the version in this repository's package.json is 6.0.3.

npm install sharedb

For local development of ShareDB itself, the repository uses Mocha and ESLint, both listed under scripts in package.json:

npm test
npm run lint

Running npm test executes mocha, which is configured by the .mocharc.yml file at the repository root. If you want to read the documentation locally, the README gives these two commands, which require Ruby above 2.4.0 and Bundler:

gem install jekyll bundler
npm run docs:install
npm run docs:start

npm run docs:start serves the docs with live reload. The README does not document a first client operation, a database adapter setup, or a pub/sub configuration in the repository README; those live in the docs site. For a runnable starting point, the repository ships examples/ directories including examples/counter, examples/counter-json1, examples/leaderboard, examples/rich-text and examples/rich-text-presence.

Where ShareDB Stops and Your Infrastructure Begins

The most important limitation is structural: ShareDB is not a database. Its dependencies are arraydiff, async, fast-deep-equal, hat and ot-json0. There is no MongoDB driver, no Postgres driver, no Redis client. The README's "Simple integration with any database" is a statement about the adapter interface, not about batteries included. You supply persistence and pub/sub, and you operate them.

That has consequences. A single-process deployment can use the in-memory implementations the README mentions for testing, but anything beyond that needs a real store and a real message bus, plus the operational work of keeping both available. If your team has no appetite for running Redis or a database cluster, ShareDB is the wrong layer to pick.

The second limitation is the OT type. Only ot-json0 is a runtime dependency. Rich text support appears in the repository as the rich-text devDependency and as examples/rich-text and examples/rich-text-presence, and ot-json1 appears as a devDependency too. The README lists "Realtime synchronization of any JSON document" as a feature, but a document type that is not JSON (binary files, for example) has no path here. Offline syncing is listed as "Offline change syncing upon reconnection," which means the client accumulates operations and replays them; how long a client can stay offline depends on how much operation history your store retains, and the README does not specify a retention policy.

ShareDB Against Yjs and Other Sync Approaches

The natural comparison is Yjs, which appears in the related searches for this project. The difference is in the data model. ShareDB transforms operations against a JSON document and keeps a versioned operation log on the server; the server is authoritative and clients submit operations to it. Yjs uses CRDTs, where each client's changes carry enough metadata to merge without a central transformation step, which is why CRDT libraries are often paired with peer-to-peer or offline-first transports.

That changes the operational profile. With ShareDB you run a server that owns document state and ordering. With a CRDT you can merge without one, at the cost of metadata growth and a different set of garbage-collection questions. Neither is strictly better; they fail in different places. If your architecture already has an authoritative backend that clients talk to, ShareDB's model matches it. If you need peers to sync without a central authority, a CRDT approach fits better.

Within the JavaScript ecosystem, DerbyJS is the framework this backend was built for, and the README points to it directly. If you are not using DerbyJS, ShareDB is still usable on its own, but you are adopting the lower half of a stack whose upper half has its own conventions. The examples in the repository (counter, leaderboard, rich-text, textarea) are the practical reference for how that lower half is meant to be driven.

Maintenance, Licence and the Cost of Upgrading

The repository is not archived, and the last push was on 2026-09-07. Recent releases are v6.0.3 on 2026-09-07, v6.0.2 on 2026-08-25 and v6.0.1 on 2026-07-06, so the 6.x line has seen patch releases within the last two months. That is a maintenance signal, but it is only a signal about activity, not about the size of the change surface.

The upgrade cost that is visible in the repository is the test matrix. devDependencies include sharedb-legacy, aliased as npm:[email protected], alongside ot-json0-v2, ot-json1 and rich-text. The presence of a 1.1.0 alias in the test dependencies suggests the project maintains compatibility tests against an older major line, which is useful if you are migrating from 1.x, but it also means the test suite is doing more than testing the current release. The changelog is at CHANGELOG.md in the repository root; read it for the 6.x entries before pinning a version.

On licensing, the README and package.json disagree in a way worth noting. package.json declares "license": "MIT", while the repository metadata carries NOASSERTION. The LICENSE file exists at the repository root. If your organisation depends on a declared SPDX identifier, check LICENSE directly rather than relying on either field, and treat this as a question for your own legal review rather than something the repository settles for you.

Editorial conclusion

Adopt ShareDB if you need concurrent edits on JSON documents and you are willing to supply the database and pub/sub adapters yourself; the package.json lists only ot-json0 and a handful of small helpers, so persistence is your integration work. Do not adopt it if you want a self-contained server with storage included, or if you need to edit plain text without a rich-text type. Before committing, verify which OT type your documents use (ot-json0 is the dependency, ot-json1 and rich-text are devDependencies in this repository), confirm the middleware hooks you need exist for your access rules, and check the changelog for the 6.x line against the version you pin.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. share/sharedb on GitHub