{"id":16529,"library":"sharedb-mongo","title":"ShareDB MongoDB Adapter","description":"sharedb-mongo is a database adapter for ShareDB, a full-stack library for realtime JSON document collaboration. It serves as both a snapshot store and an oplog for ShareDB documents, integrating directly with MongoDB. Currently at v5.1.0, the package sees active development with regular updates to support the latest Node.js and MongoDB versions. A key differentiator is its ability to unwrap JSON document snapshots, allowing direct MongoDB queries against these documents (for read-only operations), while strictly requiring ShareDB for any modifications to ensure proper operational transformation and persistence. It also extends MongoDB's querying capabilities within the ShareDB context through special `$`-prefixed operators for methods like `mapReduce` and `sort`.","status":"active","version":"5.1.0","language":"javascript","source_language":"en","source_url":"git://github.com/share/sharedb-mongo","tags":["javascript"],"install":[{"cmd":"npm install sharedb-mongo","lang":"bash","label":"npm"},{"cmd":"yarn add sharedb-mongo","lang":"bash","label":"yarn"},{"cmd":"pnpm add sharedb-mongo","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core ShareDB library that this package integrates with as a database backend.","package":"sharedb","optional":false},{"reason":"The underlying MongoDB NodeJS driver used for database interactions. Compatible with mongodb@7 since v5.1.0.","package":"mongodb","optional":false}],"imports":[{"note":"While `require` syntax is common in older examples, modern Node.js environments and TypeScript projects should use ESM `import`. The default export is a function that can be called directly or passed options.","wrong":"const ShareDbMongo = require('sharedb-mongo');","symbol":"ShareDbMongo","correct":"import ShareDbMongo from 'sharedb-mongo';"},{"note":"CommonJS usage pattern where the module itself is a function that returns a configured database instance.","symbol":"ShareDbMongo","correct":"const db = require('sharedb-mongo')('mongodb://localhost:27017/test');"},{"note":"Configuration options for the underlying MongoDB driver should typically be nested under `mongoOptions` when passed directly to the `ShareDbMongo` constructor or function call.","wrong":"new ShareDbMongo('mongodb://localhost:27017/test', { /* top-level mongo options */ });","symbol":"{ mongoOptions: {...} } (configuration)","correct":"import ShareDbMongo from 'sharedb-mongo'; new ShareDbMongo('mongodb://localhost:27017/test', { mongoOptions: { /* ... */ } });"}],"quickstart":{"code":"import ShareDB from 'sharedb';\nimport ShareDbMongo from 'sharedb-mongo';\nimport { WebSocketServer } from 'ws';\nimport http from 'http';\n\nconst mongoUrl = 'mongodb://localhost:27017/test';\nconst db = new ShareDbMongo(mongoUrl);\nconst backend = new ShareDB({ db });\n\n// Create a WebSocket server to listen for client connections\nconst server = http.createServer();\nconst wss = new WebSocketServer({ server });\n\nwss.on('connection', (ws) => {\n  // Connect client to ShareDB backend\n  const stream = backend.connect(ws);\n  // Handle stream errors\n  stream.on('error', (err) => console.error('ShareDB stream error:', err));\n});\n\nserver.listen(8080, () => {\n  console.log('ShareDB server listening on http://localhost:8080');\n  console.log(`Connected to MongoDB at ${mongoUrl}`);\n});\n\n// Example document creation (optional, for testing)\nconst connection = backend.connect();\nconst doc = connection.get('examples', 'myDocument');\ndoc.fetch((err) => {\n  if (err) throw err;\n  if (doc.type === null) {\n    doc.create({ content: 'Hello, ShareDB!' }, 'json0', (err) => {\n      if (err) console.error('Error creating document:', err);\n      else console.log('Document created!');\n    });\n  }\n});","lang":"javascript","description":"Initializes a ShareDB backend with sharedb-mongo as the database adapter and sets up a basic WebSocket server for client connections."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 18 or higher.","message":"Node.js v16 support was dropped with the release of v5.0.0. Projects using Node.js v16 or earlier must upgrade their Node.js environment to a supported version (Node.js v18 or later is recommended).","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Upgrade your Node.js runtime to version 16 or higher for sharedb-mongo v4.x, or 18+ for v5.x.","message":"Node.js v14 support was dropped with the release of v4.0.0. Users on Node.js v14 need to upgrade their runtime.","severity":"breaking","affected_versions":">=4.0.0 <5.0.0"},{"fix":"Ensure your `mongodb` package is version 3.x or higher, and your MongoDB server is compatible.","message":"Support for `mongodb@2` was dropped in v3.0.0. Users connecting to older MongoDB server versions or using older `mongodb` driver versions must upgrade their MongoDB setup.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Always use the ShareDB API to make changes to documents managed by ShareDB. Only read-only operations are safe outside of ShareDB's control.","message":"Direct modification of ShareDB documents using the native MongoDB driver or command line is strictly prohibited. This can lead to data inconsistencies and corruption as ShareDB's operational transformation mechanism will be bypassed.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"To disable: `new ShareDbMongo(mongoUrl, { disableIndexCreation: { src_seq_v: true } });`. Manually delete existing indexes if no longer needed.","message":"The default `src`/`seq`/`v` index is created automatically. If you're using `sharedb@5.0.1` or later which aims to avoid this index, you can disable its creation via `disableIndexCreation` option in `sharedb-mongo` v4.2.0+. Existing, undesired indexes must be manually deleted from MongoDB.","severity":"gotcha","affected_versions":">=4.2.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Upgrade to `sharedb-mongo@4.1.1` or later, which includes a fix for this issue. Avoid using `$map` in earlier versions.","cause":"A bug in the `$map` query transform implementation.","error":"Query hangs when using $map operator."},{"fix":"Upgrade to `sharedb-mongo@4.1.1` or later, which resolved this memory leak.","cause":"A memory leak issue affecting `mongodb@4-6` when using cursor operations such as `$count` or `$explain`.","error":"Memory leak detected when performing cursor operations like `$count`."},{"fix":"If using CommonJS, `require('sharedb-mongo')` returns a function; call it with `const db = require('sharedb-mongo')(url);`. If using ESM, ensure `import ShareDbMongo from 'sharedb-mongo';` and then `new ShareDbMongo(url);`.","cause":"Attempting to use `require('sharedb-mongo')` directly as a class constructor in CommonJS, or incorrect ESM import.","error":"TypeError: ShareDbMongo is not a constructor"}],"ecosystem":"npm"}