Registry / database / y-mongodb-provider

y-mongodb-provider

JSON →
library0.2.1jsnpmunverified

y-mongodb-provider is a database adapter that enables persistent storage and retrieval of Yjs collaborative documents using MongoDB. It serves as a backend for y-websocket servers, allowing Yjs document states to be saved and loaded, thereby ensuring data durability across server restarts or disconnections. The current stable version is 0.2.1, with updates primarily focused on dependency management, internal driver improvements, and bug fixes, indicating an active development status though without a strict release cadence. Key differentiators include its specific integration with MongoDB (unlike Yjs's officially supported y-leveldb), its ability to handle Yjs updates exceeding MongoDB's 16MB document size limit (since v0.1.8), and its use of the official MongoDB Node.js Driver for enhanced security and performance. It's important to note that this package is not officially supported by the Yjs team.

npm install y-mongodb-provider
INSTALL
IMPORT
SIG · Y-MONGODB-PROVIDER
Y
y-mongodb-provider
databasejavascriptv0.2.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

MongodbPersistence
import { MongodbPersistence } from 'y-mongodb-provider'
const { MongodbPersistence } = require('y-mongodb-provider')
This package is primarily ESM-first, requiring Node.js 16+. Named import is the standard way. Ships TypeScript types.
MongodbPersistence constructor (connection string)
new MongodbPersistence('mongodb://localhost:27017/yjstest')
The constructor accepts a MongoDB connection string. Since v0.2.0+, ensure proper database name in the string for authentication purposes.
MongodbPersistence constructor (client object)
import { MongoClient } from 'mongodb'; const client = new MongoClient('mongodb://localhost:27017'); await client.connect(); const db = client.db('yourDatabaseName'); new MongodbPersistence({ client, db })
Passing an object with `MongoClient` and `Db` instances is recommended for managing connection pools and resource sharing, especially when the same client is used elsewhere in your application.

This example sets up a Yjs WebSocket server using `y-websocket` and integrates `y-mongodb-provider` for persistent storage of Yjs document states in a MongoDB database. It demonstrates binding document state on connection and asynchronously storing updates as they occur.

import http from 'http'; import { WebSocketServer } from 'ws'; import * as Y from 'yjs'; import { MongodbPersistence } from 'y-mongodb-provider'; import yUtils from 'y-websocket/bin/utils'; // Note: y-websocket/bin/utils is an internal utility, adapt as needed. const port = process.env.PORT || 1234; const mongoConnectionString = process.env.MONGODB_URL || 'mongodb://localhost:27017/yjstest'; const server = http.createServer((request, response) => { response.writeHead(200, { 'Content-Type': 'text/plain' }); response.end('okay'); }); // Initialize Yjs WebSocket server const wss = new WebSocketServer({ server }); wss.on('connection', yUtils.setupWSConnection); // Initialize MongoDB persistence for Yjs const mdb = new MongodbPersistence(mongoConnectionString, { collectionName: 'transactions', flushSize: 100, multipleCollections: false, // Default; set to true if each document needs its own collection }); // Set up persistence with y-websocket yUtils.setPersistence({ bindState: async (docName, ydoc) => { // Retrieve the persisted document state const persistedYdoc = await mdb.getYDoc(docName); // Apply the persisted state to the current ydoc Y.applyUpdate(ydoc, Y.encodeStateAsUpdate(persistedYdoc)); // Store initial state and listen for future updates mdb.storeUpdate(docName, Y.encodeStateAsUpdate(ydoc)); ydoc.on('update', async (update) => { mdb.storeUpdate(docName, update); }); }, writeState: async (docName, ydoc) => { // This function is called when all connections to a document are closed. // Ensure all pending updates are written to the database. // For y-mongodb-provider, `storeUpdate` handles this incrementally. // The promise resolution signals that the document can be destroyed. return new Promise(resolve => resolve()); }, }); server.listen(port, () => { console.log(`Yjs WebSocket server with MongoDB persistence listening on port: ${port}`); });
Debug
Known issues
gotchaThis `y-mongodb-provider` package is not officially supported or maintained by the core Yjs team. While functional, users should be aware of its community-driven support model.
fix
Review the GitHub repository for active development, open issues, and pull requests to gauge maintenance status and potential issues. Consider contributing to its development if you find gaps.
affects: >=0.1.6
breakingNode.js version 16 or newer is required to use this package. Using older Node.js versions will result in runtime errors due to reliance on modern JavaScript features and ESM module format.
fix
Upgrade your Node.js environment to version 16 or later (e.g., `nvm install 16 && nvm use 16`).
affects: >=0.1.6
breakingVersion 0.1.8 replaced the internal 'mongoist' library with the official 'mongodb' Node.js Driver. While the public API signature for `MongodbPersistence` generally remained, internal behaviors, error handling, or specific connection options might have changed. This change was also made for security enhancements.
fix
Review the official MongoDB Node.js driver documentation for any specific connection string options or client configurations, especially if encountering unexpected behavior when migrating from versions prior to 0.1.8.
affects: >=0.1.8
gotchaFor optimal performance and robust connection pooling, especially when sharing a `MongoClient` instance across your application, it is recommended to pass an object `{ client: MongoClient, db: Db }` to the `MongodbPersistence` constructor instead of just a connection string. This avoids creating redundant MongoDB client instances.
fix
Manually instantiate `MongoClient`, connect it, and pass the `{ client, db: client.db('yourDatabaseName') }` object to the `MongodbPersistence` constructor.
affects: >=0.1.6
gotchaIf the `multipleCollections` option is set to `true` in the `MongodbPersistence` constructor, each Yjs document will be stored in its own dedicated MongoDB collection. In this scenario, the `collectionName` option will be ignored.
fix
Ensure that if you intend to store all documents within a single, named collection, `multipleCollections` must be set to `false` (which is its default value).
affects: >=0.1.6
breakingVersion 0.2.0 introduced changes to the `MongodbPersistence` constructor's internal handling of the database name for user authentication. While passing a connection string is still supported, improper database naming could lead to authentication failures or incorrect access rights.
fix
Verify that the database name specified in your MongoDB connection string or through the `client.db('databaseName')` call accurately corresponds to the database against which your MongoDB user is authenticated and has the necessary permissions.
affects: >=0.2.0
Upgrade
Version history
0.2.1latest on npm
Audit
Dependencies
yjsrequiredCore Yjs library, required for Yjs document structure and operations.
Agent activity
47 hits · last 30 days
node
38
Meta
1
Amazon
1
Resources