sharedb

library2.0.2jsnpmunverified

ShareDB is a powerful realtime database backend built on Operational Transformation (OT) for JSON documents, enabling concurrent multi-user collaboration and synchronous editing with eventual consistency. It is the core realtime backend for the DerbyJS web application framework. Currently in version 5.2.2, ShareDB maintains a consistent release cadence with frequent patch and minor updates addressing bugs and performance improvements. Key features include realtime query subscriptions, easy integration with various databases (like MongoDB via `sharedb-mongo`), horizontal scalability through pub/sub, document projections, middleware support for access control, and offline change syncing. It supports both server-side and browser environments and provides access to historic document versions and realtime user presence syncing. It differentiates itself by offering a complete OT-based solution for collaborative data management.

database web-framework

npm install sharedb

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SHAREDB

sharedb

databasejavascriptv2.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Backend

✓ import { Backend } from 'sharedb';

✗ const Backend = require('sharedb');

While CommonJS `require` might still work in Node.js, ESM `import` is the recommended and modern approach. ShareDB v5.0.0 dropped Node.js v16 support, aligning with more modern module practices.

MemoryDB

✓ import { MemoryDB } from 'sharedb';

✗ import MemoryDB from 'sharedb/lib/db/memory';

MemoryDB is often used for testing and is directly exposed from the main package for convenience. Avoid deep imports from internal paths.

MemoryPubSub

✓ import { MemoryPubSub } from 'sharedb';

✗ import MemoryPubSub from 'sharedb/lib/pubsub/memory';

MemoryPubSub, like MemoryDB, is included for development and testing purposes and is exported directly from the main package.

This quickstart demonstrates setting up a basic ShareDB server with in-memory storage and pub/sub, integrated with a WebSocket server. It initializes the backend, connects a WebSocket server, and shows how to create a document using a ShareDB connection.

import { Backend, MemoryDB, MemoryPubSub } from 'sharedb'; import WebSocket from 'ws'; import http from 'http'; const backend = new Backend({ db: new MemoryDB(), pubsub: new MemoryPubSub() }); const server = http.createServer((req, res) => { res.writeHead(200, { 'Content-Type': 'text/plain' }); res.end('ShareDB Server\n'); }); const wss = new WebSocket.Server({ server: server }); wss.on('connection', (ws) => { const stream = new WebSocket.WebSocketJSONStream(ws); backend.listen(stream); }); server.listen(8080, () => { console.log('ShareDB server listening on http://localhost:8080'); // Example: Create a new document via a connection const connection = backend.connect(); const doc = connection.get('myCollection', 'myDocument'); doc.fetch((err) => { if (err) throw err; if (doc.type === null) { doc.create({ message: 'Hello, ShareDB!' }, 'json0', () => { console.log('Document created:', doc.data); }); } else { console.log('Document already exists:', doc.data); } }); }); // To run this, you'll need 'ws' and 'sharedb' installed. // For the client-side stream, you might need 'rich-websocket-jsonstream' or similar.

Debug

Known issues

breakingShareDB v5.0.0 removed support for Node.js v16. Projects relying on older Node.js versions must upgrade their environment to Node.js v18 or newer.

fix

Upgrade your Node.js runtime environment to version 18 or higher.

affects: >=5.0.0

gotchaWhen initializing the ShareDB Backend, it is crucial to provide a database and a pub/sub adapter. Failing to do so will result in an unworkable setup, as ShareDB requires these components for persistence and real-time communication.

fix

Always pass `db` and `pubsub` options to the `new Backend()` constructor, e.g., `new Backend({ db: new MemoryDB(), pubsub: new MemoryPubSub() })` or use specific implementations like `sharedb-mongo` and Redis pub/sub.

affects: >=1.0.0

gotchaShareDB relies on a 'json0' operational transformation type by default. If you intend to use other OT types or custom operations, ensure they are registered and correctly applied, or document operations might not behave as expected.

fix

Understand the 'json0' OT type for JSON operations. For custom types, extend ShareDB's type system or use `share/types` to register them correctly for your documents.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'db')

The ShareDB `Backend` was instantiated without providing a `db` option in its configuration.

fix

Initialize `new Backend({ db: new YourDatabaseAdapter() })`. For testing, `new MemoryDB()` can be used.

Error: Middleware 'connection' must be a function

An incorrect type was passed as a middleware function for a ShareDB hook.

fix

Ensure that any function assigned to a middleware hook (e.g., `backend.use('connection', (request, next) => { ... })`) is indeed a function.

ReferenceError: WebSocket is not defined (in Node.js environment)

The `WebSocket` class is a browser API and is not globally available in Node.js without a specific polyfill or library.

fix

When running ShareDB servers in Node.js, install and import a WebSocket library like `ws`: `import WebSocket from 'ws';`

Upgrade

Version history

2.0.2latest on npm

Audit

Dependencies

sharedb-mongooptionalCommonly used MongoDB database adapter for persistence.

wsoptionalWebSocket library often used to integrate ShareDB with a server for real-time communication.

Agent activity

15 hits · last 30 days

node