Registry / devops / serverless-mongodb-local

serverless-mongodb-local

library1.6.0jsnpmunverified

Serverless plugin that automatically starts and stops a local MongoDB instance using mongodb-memory-server. Downloads MongoDB binaries on first use. Serves as a local equivalent to DocumentDB/CosmosDB for development and testing. Compatible with Serverless Framework v2 and v3. Released under MIT license, last updated in 2023. Key differentiator: integrates seamlessly into Serverless offline workflows, supports seeding from JSON files, and provides environment variables for connection URIs. Alternative to using a separate MongoDB installation or Docker container.

devops database

npm install serverless-mongodb-local

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SERVERLESS-MONGODB

serverless-mongodb-local

devopsjavascriptv1.6.0

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.

plugin

✓ plugins: - serverless-mongodb-local

✗ plugins: - serverless-mongodb-local - serverless-offline # must be listed after

Plugin is configured via serverless.yml; no JavaScript import required. If using serverless-offline, ensure serverless-mongodb-local is listed above it.

MongoClient

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

✗ import { MongoClient } from 'mongodb'; // ESM not supported in older Node versions

Use the mongodb driver to connect; URI is provided via process.env.SLS_MONGODB_URI when --localEnvironment flag is set.

MongoMemoryServer

✓ import { MongoMemoryServer } from 'mongodb-memory-server';

✗ const MongoMemoryServer = require('mongodb-memory-server');

Direct use of MongoMemoryServer is optional; plugin handles it internally. ESM import is available in mongodb-memory-server v8+.

Install, configure in serverless.yml, and use the provided MongoDB URI environment variable in a handler.

npm i -D serverless-mongodb-local # serverless.yml plugins: - serverless-mongodb-local custom: mongodb: stages: - dev instance: port: 27017 dbName: mydb seed: auto: true dataPath: ./test/data # handlers.js const { MongoClient } = require('mongodb'); module.exports.handler = async (event) => { const client = new MongoClient(process.env.SLS_MONGODB_URI ?? 'mongodb://localhost:27017'); await client.connect(); const db = client.db(); const result = await db.collection('test').findOne({}); return { statusCode: 200, body: JSON.stringify(result) }; }; # Run: sls offline start --localEnvironment

Debug

Known issues

gotchaThe environment variable SLS_MONGODB_URI is only set when the --localEnvironment flag is provided on the command line. Without it, the variable is undefined.

fix

Always include --localEnvironment when running offline: sls offline start --localEnvironment

affects: >=1.0.0

gotchaPlugin order matters when used with serverless-offline. serverless-mongodb-local must be listed before serverless-offline in the plugins array, otherwise the MongoDB instance may not start before your handlers run.

fix

In serverless.yml, list serverless-mongodb-local above serverless-offline.

affects: >=1.0.0

breakingVersion 1.0.0 dropped support for serverless v1. Only v2 and v3 are supported.

fix

Update serverless to v2 or v3.

affects: >=1.0.0 <2.0.0

deprecatedThe dbName configuration option is deprecated and may be removed in future versions. Use the databaseName option instead.

fix

Replace dbName with databaseName in serverless.yml.

affects: >=1.0.0

gotchaIf you set dbPath and storageEngine, the database will persist between instantiations. This can lead to unexpected state if you expect a fresh database each time.

fix

Omit dbPath or storageEngine to get a fresh instance each time.

affects: >=1.0.0

Errors

Common errors & fixes

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

process.env.SLS_MONGODB_URI is undefined because --localEnvironment flag was omitted

fix

Add --localEnvironment to your command: sls offline start --localEnvironment

Error: Cannot find module 'serverless-mongodb-local'

Plugin not installed or not listed in serverless.yml

fix

Run npm i -D serverless-mongodb-local and ensure it's in the plugins array.

MongoNetworkError: connect ECONNREFUSED 127.0.0.1:27017

MongoDB instance not started or wrong port

fix

Check that the plugin is loaded before serverless-offline and that the port matches custom.mongodb.instance.port.

Error: MongoMemoryServer: requested version 4.0.0 is not available

The specified MongoDB version is not available for download on your platform/architecture

fix

Remove or change the version in custom.mongodb.instance.binary.version. If not set, it defaults to latest.

Upgrade

Version history

1.6.0latest on npm

Audit

Dependencies

serverlessrequiredpeer dependency required for plugin to function

mongodb-memory-serverrequiredprovides MongoDB binary download and lifecycle management

Agent activity

10 hits · last 30 days

node