@ynode/mongoose

Copyright (c) 2026 Michael Welter [email protected]

A better Mongoose Fastify plugin for connection sharing and useful logging

Why?

A lightweight Fastify plugin that exposes a single mongoose client (mongoose package) on your Fastify instance and handles connection lifecycle (connect → ready → reconnect → close) for you.

• ✅ Uses the official mongoose client
• ✅ Clean Fastify integration with proper startup/shutdown hooks
• ✅ Simple API: fastify.mongoose everywhere in your app

Installation

Requires Node.js 20.19.0 or newer, Fastify 5, and Mongoose 9. Install the package and its Mongoose peer dependency:

npm install @ynode/mongoose mongoose

Usage

Register the plugin with your Fastify instance. You MUST provide a uri option. By default, startup waits for MongoDB (waitForConnection: true). Options other than uri and waitForConnection are passed to connection.openUri(uri, options).

Registering the Plugin

import Fastify from "fastify";
import fastifyMongoose from "@ynode/mongoose";

const fastify = Fastify({
    logger: true,
});

// Register the plugin with options
await fastify.register(fastifyMongoose, {
    uri: "mongodb://localhost:27017/my_database",
    waitForConnection: true,
    // Options below are passed to connection.openUri(uri, options)
    maxPoolSize: 10,
});

// JavaScript also supports a runtime-only connection-string shortcut.
// TypeScript callers should use the object form above.
await fastify.register(fastifyMongoose, "mongodb://localhost:27017/my_database");

// For non-blocking startup behavior
await fastify.register(fastifyMongoose, {
    uri: "mongodb://localhost:27017/my_database",
    waitForConnection: false,
});

Using the Connection

The Mongoose connection is available at fastify.mongoose. You should use this connection to create your models to ensure they are bound to this specific connection.

// Define a schema
const UserSchema = new fastify.mongoose.base.Schema({
    name: String,
    email: String,
});

// Create a model attached to this connection
// Note: We use fastify.mongoose.model, NOT the global mongoose.model
const User = fastify.mongoose.model("User", UserSchema);

// Route example
fastify.get("/users", async (request, reply) => {
    const users = await User.find();
    return users;
});

const start = async () => {
    try {
        await fastify.listen({ port: 3000 });
    } catch (err) {
        fastify.log.error(err);
        process.exit(1);
    }
};

start();

Options

This plugin forwards options other than uri and waitForConnection to connection.openUri(uri, options) from the official mongoose library.

• waitForConnection (boolean, default: true): if true, fastify.ready() fails when initial MongoDB connection fails. If false, startup continues while one initial connection attempt runs in the background. The plugin does not retry a failed initial attempt; Mongoose reconnects automatically only after an initial connection succeeds.

For a full list of available options, please see the official mongoose documentation.

Failure Behavior

• The plugin starts connecting during Fastify onReady.
• waitForConnection: true (default): startup fails if the initial connection attempt fails.
• waitForConnection: false: startup is non-blocking and one failed initial attempt is logged without retrying.
• Connection lifecycle events (connected, disconnected, reconnected, error, close) are logged. Intentional shutdown disconnects are not warned as outages.
• On shutdown, the plugin awaits connection.close(). Mongoose safely joins connections that are still connecting or already disconnecting.

For readiness checks, inspect fastify.mongoose.readyState (1 means connected). The plugin does not register a health route or perform database pings.

License

This project is licensed under the MIT License.