{"id":17362,"library":"sharedb","title":"ShareDB: Realtime JSON OT Database Backend","description":"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.","status":"active","version":"5.2.2","language":"javascript","source_language":"en","source_url":"git://github.com/share/sharedb","tags":["javascript"],"install":[{"cmd":"npm install sharedb","lang":"bash","label":"npm"},{"cmd":"yarn add sharedb","lang":"bash","label":"yarn"},{"cmd":"pnpm add sharedb","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Commonly used MongoDB database adapter for persistence.","package":"sharedb-mongo","optional":true},{"reason":"WebSocket library often used to integrate ShareDB with a server for real-time communication.","package":"ws","optional":true}],"imports":[{"note":"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.","wrong":"const Backend = require('sharedb');","symbol":"Backend","correct":"import { Backend } from 'sharedb';"},{"note":"MemoryDB is often used for testing and is directly exposed from the main package for convenience. Avoid deep imports from internal paths.","wrong":"import MemoryDB from 'sharedb/lib/db/memory';","symbol":"MemoryDB","correct":"import { MemoryDB } from 'sharedb';"},{"note":"MemoryPubSub, like MemoryDB, is included for development and testing purposes and is exported directly from the main package.","wrong":"import MemoryPubSub from 'sharedb/lib/pubsub/memory';","symbol":"MemoryPubSub","correct":"import { MemoryPubSub } from 'sharedb';"}],"quickstart":{"code":"import { Backend, MemoryDB, MemoryPubSub } from 'sharedb';\nimport WebSocket from 'ws';\nimport http from 'http';\n\nconst backend = new Backend({\n  db: new MemoryDB(),\n  pubsub: new MemoryPubSub()\n});\n\nconst server = http.createServer((req, res) => {\n  res.writeHead(200, { 'Content-Type': 'text/plain' });\n  res.end('ShareDB Server\\n');\n});\n\nconst wss = new WebSocket.Server({ server: server });\n\nwss.on('connection', (ws) => {\n  const stream = new WebSocket.WebSocketJSONStream(ws);\n  backend.listen(stream);\n});\n\nserver.listen(8080, () => {\n  console.log('ShareDB server listening on http://localhost:8080');\n  // Example: Create a new document via a connection\n  const connection = backend.connect();\n  const doc = connection.get('myCollection', 'myDocument');\n\n  doc.fetch((err) => {\n    if (err) throw err;\n    if (doc.type === null) {\n      doc.create({ message: 'Hello, ShareDB!' }, 'json0', () => {\n        console.log('Document created:', doc.data);\n      });\n    } else {\n      console.log('Document already exists:', doc.data);\n    }\n  });\n});\n\n// To run this, you'll need 'ws' and 'sharedb' installed.\n// For the client-side stream, you might need 'rich-websocket-jsonstream' or similar.","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js runtime environment to version 18 or higher.","message":"ShareDB 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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"ShareDB 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Initialize `new Backend({ db: new YourDatabaseAdapter() })`. For testing, `new MemoryDB()` can be used.","cause":"The ShareDB `Backend` was instantiated without providing a `db` option in its configuration.","error":"TypeError: Cannot read properties of undefined (reading 'db')"},{"fix":"Ensure that any function assigned to a middleware hook (e.g., `backend.use('connection', (request, next) => { ... })`) is indeed a function.","cause":"An incorrect type was passed as a middleware function for a ShareDB hook.","error":"Error: Middleware 'connection' must be a function"},{"fix":"When running ShareDB servers in Node.js, install and import a WebSocket library like `ws`: `import WebSocket from 'ws';`","cause":"The `WebSocket` class is a browser API and is not globally available in Node.js without a specific polyfill or library.","error":"ReferenceError: WebSocket is not defined (in Node.js environment)"}],"ecosystem":"npm","meta_description":null}