@julienmoulis/mongo-singleton

A MongoDB connection singleton that survives Next.js hot reloads. Prevents connection pool exhaustion during development by reusing a single MongoClient instance stored in globalThis.

Installation

npm install @julienmoulis/mongo-singleton mongodb

mongodb is a peer dependency (>=5.0.0).

Quick Start

import { createMongoSingleton } from "@julienmoulis/mongo-singleton";

const mongo = createMongoSingleton({
  uri: "mongodb://localhost:27017",
});

// Get a database
const db = await mongo.getDb("myapp");

// Or get the raw client
const client = await mongo.getClient();

Environment Variable

If no uri option is provided, the singleton falls back to the MONGODB_URI environment variable:

const mongo = createMongoSingleton(); // uses process.env.MONGODB_URI

Options

| Option | Type | Default | Description | |---|---|---|---| | uri | string | process.env.MONGODB_URI | MongoDB connection URI | | maxPoolSize | number | 10 | Max connections in pool | | minPoolSize | number | 1 | Min connections in pool | | logger | function \| null | console | Custom logger. Pass null to silence all logs | | onConnect | (client: MongoClient) => void | — | Called once after successful connection |

API

createMongoSingleton(options?): MongoSingleton

Returns an object with:

• getClient() — Returns Promise<MongoClient>. Connects on first call, reuses the connection afterwards.
• getDb(dbName) — Returns Promise<Db>. Shorthand for client.db(dbName).
• close() — Closes the connection and clears the cached client.

Multiple Connections

Each unique URI gets its own singleton, so you can safely create multiple instances pointing to different databases:

const primary = createMongoSingleton({ uri: "mongodb://primary:27017" });
const analytics = createMongoSingleton({ uri: "mongodb://analytics:27017" });

Graceful Shutdown

Cleanup handlers are automatically registered for SIGINT, SIGTERM, and beforeExit to close the connection when the process exits.

License

MIT