ShareDB 7.0.0: OT sync for JSON, projections and middleware, and docs that need Ruby

Eventual consistency sits behind a synchronous editing API

The feature list states the tradeoff in a single line: a synchronous editing API with asynchronous eventual consistency. Reads and writes look like ordinary function calls, and what sits underneath is Operational Transformation over JSON documents. Concurrent multi-user collaboration and realtime synchronization of any JSON document are consequences of that design rather than separate modes you switch on.

Two more entries describe what happens when the network is not there. Offline change syncing upon reconnection covers the disconnected case, and access to historic document versions covers going back. Realtime user presence syncing is a separate stream from document content, which is what lets an application show who is looking at a document without conflating that with edits.

The list also names realtime query subscriptions, which is the feature that reaches past single documents. That is the piece to examine first if your data does not fit a one-document-per-conversation shape.

The npm tarball ships lib and test, so examples never reach a consumer

package.json carries an explicit files array with two entries, `lib/` and `test/`. That is the whole published surface. The `examples/` directory stays in the repository and does not travel to npm, which means the Counter and Leaderboard demos have to be read from source rather than installed alongside the package.

Two of those examples are named directly in the README as the starting points, Counter and Leaderboard. The full example tree is wider than that: counter, counter-json1, counter-json1-vite, leaderboard, rich-text, rich-text-presence, and textarea. Reading the tree tells you the document formats in play. There is a JSON0 counter and a JSON1 counter, a Vite-hosted variant, two rich text examples that differ by whether presence is included, and a plain textarea example.

Shipping test/ is the unusual half of that decision. Consumers get the test suite on every install, which makes the package heavier but lets a downstream project check its own assumptions against the upstream expectations.

hat sits at an exact version while the rest of the runtime deps use ranges

There are five runtime dependencies, and they are not all pinned the same way. arraydiff, async, fast-deep-equal, and ot-json0 all take caret ranges. `hat` takes `0.0.3` with no range operator at all.

That matters because of how the caret behaves. A caret on a zero major version, which is where arraydiff sits at ^0.1.3, allows patch level movement but nothing else; ot-json0 at ^1.1.0 has a non-zero major, so its caret also admits minor releases. The exact pin on hat is the strictest case in the list: the installed version is the one named.

The rest of the dependency picture is dev-only. That set includes mocha, chai, sinon, sinon-chai, nyc, eslint and its Google-flavoured config, plus ot-json1 and rich-text as alternate document types used in tests, and a sharedb alias that installs an old published version of this same package for comparison. The build and test scripts stay small: `mocha` for the suite, `eslint` for linting, and an nyc wrapper for coverage.

The entry point is `lib/index.js`, and the package does not declare an ES module type field.

sharedb-legacy pulls 1.1.0 in next to 6.0.3 for compatibility tests

One dev dependency is worth reading twice: `sharedb-legacy` resolves to `npm:[email protected]`, which is an alias pointing at a specific old release of this project itself. The current version in package.json is 7.0.0, so the test environment has two major versions of ShareDB installed at once.

That arrangement is a deliberate compatibility harness rather than an accident of dependency resolution. Behaviour that has to stay stable across a major version gap, such as the wire format of operations or the shape of a document, can be tested against both.

The other pins in the dev set carry the same care. ot-json0-v2 is not taken from a registry at all: it is a direct git URL pinned to one commit hash, which fixes the exact revision rather than a version number. ot-json1 and rich-text come as ordinary ranges.

Documentation runs on Jekyll, so building the docs needs a second toolchain

The docs are stored as Markdown and served with Jekyll, which means Ruby >2.4.0 and Bundler rather than anything from the Node side. The README gives the prerequisite as one command:

gem install jekyll bundler

Once that is in place, two npm scripts drive the site from the repository root:

npm run docs:install
npm run docs:start

Those map to `cd docs && bundle install` and `cd docs && bundle exec jekyll serve --livereload`. A third script, `npm run docs:build`, runs the same Jekyll build without serving, which is the one a pipeline would use. Note that all three shell out into the docs directory and hand the work to Ruby, so a contributor without a Ruby toolchain can read the Markdown but cannot preview the site.

The published documentation lives at a separate site rather than in the package, and the package's files array keeps it out of the tarball entirely.

Projections and middleware are the only named extension points

Of the thirteen feature entries, two describe hooks rather than behaviour. Projections select desired fields from documents and operations, and middleware exists for implementing access control and custom extensions. Everything else in the list is a capability you consume rather than a seam you extend.

Projections are the one with performance implications. Since they operate on both documents and operations, a projection can cut the payload a client receives, and that is where a realtime backend either keeps a channel cheap or makes every edit a heavy message. The wording does not say which direction projections help in, so treat the claim as a capability and check the documented semantics before relying on it for bandwidth.

Middleware is what stands between ShareDB and your authorization rules. The feature list names access control as its motivating case, which tells you the hook exists at a point where you can reject operations, but it does not describe the interface, the ordering, or whether middleware also sees presence and query subscriptions. For a collaboration product that is the single most important page to read, and the README does not summarise it.

Horizontal scale depends on a pub/sub adapter you have to supply

Two entries describe scaling and storage, and neither names a default. Horizontally scalable with pub/sub integration means the fan-out layer is pluggable, and simple integration with any database means the persistence layer is too. Nothing in the repository listing suggests a bundled adapter: the tree at the root is .github, .mocharc.yml, CHANGELOG.md, LICENSE, README.md, docs, eslint.config.js, examples, lib, package.json, scripts, and test.

For tests the answer is in the feature list: in-memory implementations of database and pub/sub exist for unit testing. That is the substitute you would reach for in a test suite, and it also hints at the shape of the production interfaces, since an in-memory implementation only works if the interface itself is small.

The project is the realtime backend for the DerbyJS web application framework, and the feature list claims the library is ideal for use in browsers or on the server without naming a client repository. Support is the ShareJS mailing list plus the issue tracker, and the package authors are Nate Smith and Joseph Gentle. The repository is not archived, and the last push is dated 2026-10-30, with recent tagged releases v6.0.4 on 2026-10-05 and v6.0.5 and v7.0.0 both on 2026-10-22.

Editorial conclusion

ShareDB earns its place when you need concurrent editing of JSON documents with a synchronous call surface, offline change syncing on reconnect, presence, and a pub/sub layer for horizontal scale. It is a poor fit if your team has no appetite for an OT-specific document model. Before adopting, read the documentation at share.github.io/sharedb to see which database adapter you would use, confirm you actually need projections rather than reshaping on the client, and check what the middleware hook lets you enforce, since access control is built on it.

Frequently asked questions

Official sources

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