Registry / database / botbuilder-storage-mongodb

botbuilder-storage-mongodb

library1.0.17jsnpmunverified

MongoDB storage provider for the Bot Framework JavaScript SDK v4. This library implements the `Storage` interface, allowing bots to persist conversation state, user state, and bot state in a MongoDB database. The current version (1.0.17) supports Node.js 13+ and is compatible with the BotBuilder v4 SDK. It exposes a simple API: create a `MongoDbStorage` instance with a MongoDB collection, then use it with `ConversationState` or `UserState`. The library provides a convenience method `getCollection()` that defaults to database `BotFramework` and collection `BotFrameworkState`, but supports custom names. Compared to the official botbuilder-azure storage, this package is community-maintained and offers a lightweight, pure-MongoDB solution without Azure dependencies.

database

npm install botbuilder-storage-mongodb

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BOTBUILDER-STORAGE

botbuilder-storage-mongodb

databasejavascriptv1.0.17

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

MongoDbStorage

✓ import { MongoDbStorage } from 'botbuilder-storage-mongodb';

✗ const MongoDbStorage = require('botbuilder-storage-mongodb');

The package exports a single class as a named export. CommonJS require will not work because the default export is undefined. Always use destructured import.

MongoDbStorage

✓ const { MongoDbStorage } = require('botbuilder-storage-mongodb');

✗ const MongoDbStorage = require('botbuilder-storage-mongodb').MongoDbStorage;

CommonJS usage is possible via destructuring require. The wrong pattern shown is actually correct — this is not a common mistake; both destructuring and dot-access work.

MongoClient

✓ import { MongoClient } from 'mongodb';

✗ const { MongoClient } = require('mongodb');

MongoClient is from the 'mongodb' package, not from this package. Ensure both are installed.

Connect to MongoDB, create a MongoDbStorage instance, then write and read bot state.

const { MongoClient } = require('mongodb'); const { MongoDbStorage } = require('botbuilder-storage-mongodb'); async function main() { const client = new MongoClient('mongodb://localhost:27017/', { useUnifiedTopology: true }); await client.connect(); const collection = client.db('BotFramework').collection('BotFrameworkState'); const storage = new MongoDbStorage(collection); // Example: write and read state const changes = { 'user/abc': { data: { name: 'Alice' }, eTag: '*' } }; await storage.write(changes); const keys = ['user/abc']; const items = await storage.read(keys); console.log('Read state:', items['user/abc']); await client.close(); } main().catch(console.error);

Debug

Known issues

breakingIn version 1.0.0, the constructor signature changed from MongoDbStorage(connectionString, dbName, collectionName) to MongoDbStorage(collection). The old signature is removed.

fix

Upgrade to v1+ and pass a MongoCollection object directly.

affects: <1.0.0

deprecatedThe static method `getCollection()` is deprecated as of v1.0.8. It remains available but will be removed in a future release.

fix

Use `new MongoClient(url).db(dbName).collection(collectionName)` to create the collection explicitly.

affects: >=1.0.8

gotchaThe `eTag` property in state changes must be `'*'` for a forced write (first write) or the existing `eTag` from a previous read. Using an incorrect eTag value causes optimistic concurrency failures.

fix

Always read before write to get the current eTag, or use '*' to force overwrite.

affects: *

gotchaThe `useUnifiedTopology` option is required for MongoDB driver >=3.1.0. Without it, the connection will fail or emit deprecation warnings.

fix

Pass `{ useUnifiedTopology: true }` to the MongoClient constructor.

affects: *

gotchaState documents are stored with a `_id` field (the state key) and a `document` field containing the serialized state. This internal structure must not be modified manually.

fix

Always use the storage interface read/write methods; do not query the collection directly.

affects: *

Errors

Common errors & fixes

TypeError: MongoDbStorage is not a constructor

Using default import (`import MongoDbStorage from ...`) or incorrect require (no destructuring).

fix

Use named import: `import { MongoDbStorage } from ...` or `const { MongoDbStorage } = require(...)`

Error: Collection must be provided.

Calling `MongoDbStorage()` constructor without a collection argument.

fix

Pass a valid MongoCollection object: `new MongoDbStorage(collection)`

MongoError: bad auth Authentication failed.

Invalid credentials or missing authMechanism option in connection string.

fix

Use `mongodb://user:password@host:port/db?authSource=admin` with proper URL encoding.

DeprecationWarning: current Server Discovery and Monitoring engine is deprecated

Missing `useUnifiedTopology` option in MongoClient constructor.

fix

Add `{ useUnifiedTopology: true }` as the second parameter to the MongoClient constructor.

Upgrade

Version history

1.0.17latest on npm

Audit

Dependencies

botbuilderrequiredPeer dependency for `Storage` interface and `ConversationState`/`UserState` classes

mongodbrequiredNative MongoDB driver for connecting and querying MongoDB

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/botbuilder-contrib/botbuilder-storage-mongodb ↗

packagebotbuilder-storage-mongodb ↗

homepagehttps://github.com/botbuilder-contrib/botbuilder-storage-mongodb#readme ↗