In this tutorial, we’ll walk through the process of connecting MongoDB to a Next.js application. We’ll cover how to set up MongoDB using Mongoose, connect to MongoDB Atlas, and ensure efficient database connections in your Next.js API routes.

Prerequisites

Basic understanding of JavaScript and Next.js.
Installed MongoDB locally or an active MongoDB Atlas account.
Basic knowledge of Node.js and npm.

Step 1: Install MongoDB and Mongoose

First, you need to install mongoose, the popular Node.js library for MongoDB, in your Next.js project.

npm install mongoose
Mongoose provides an elegant solution for managing MongoDB connections and defining schemas for data models.

Step 2: Set Up MongoDB Atlas

If you don’t have MongoDB installed locally, you can use MongoDB Atlas, a cloud-hosted MongoDB service.

Sign up at MongoDB Atlas.
Create a new project and cluster.
Get the connection string by clicking "Connect" in the cluster dashboard.

Format:
mongodb+srv://<username>:<password>@cluster0.mongodb.net/<dbname>?retryWrites=true&w=majority

Replace <username>, <password>, and <dbname> with your actual credentials.

Step 3: Create a .env File
In the root of your Next.js project, create a file named .env.local. This file will hold your environment variables securely.

MONGODB_URI=mongodb+srv://<username>:<password>@cluster0.mongodb.net/<dbname>?retryWrites=true&w=majority

Make sure to replace the placeholders with your actual MongoDB connection string. This allows you to access the URI using process.env.MONGODB_URI in your code.

Step 4: Create a Database Connection Utility
Create a utility file to manage the connection between your Next.js app and MongoDB. This file ensures that MongoDB connects efficiently, especially when handling multiple requests in a serverless environment.

/lib/db.ts

import mongoose from 'mongoose';

const MONGODB_URI = process.env.MONGODB_URI;

if (!MONGODB_URI) {
  throw new Error('Please define the MONGODB_URI environment variable');
}

let cached = global.mongoose;

if (!cached) {
  cached = global.mongoose = { conn: null, promise: null };
}

async function dbConnect() {
  if (cached.conn) {
    return cached.conn;
  }

  if (!cached.promise) {
    const opts = {
      bufferCommands: false,
    };

    cached.promise = mongoose.connect(MONGODB_URI, opts).then((mongoose) => {
      return mongoose;
    });
  }

  cached.conn = await cached.promise;
  return cached.conn;
}

export default dbConnect;

Explanation:

We define a dbConnect function that ensures MongoDB connects once and reuses the connection for subsequent requests. This helps optimize performance in serverless environments like Vercel.
If there’s already a connection (cached.conn), it reuses it instead of reconnecting.

Step 5: Use the Connection in API Routes

Now that we have the connection utility, let’s use it in an API route. Create a simple route that connects to MongoDB and returns all users.

/pages/api/users.ts

import { NextApiRequest, NextApiResponse } from 'next';
import dbConnect from '@/lib/db';
import User from '@/lib/models/User';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  await dbConnect();

  const users = await User.find({});

  res.status(200).json({ success: true, data: users });
}

Explanation:

This API route connects to MongoDB and retrieves all users from the User model.
The connection is established using dbConnect, ensuring MongoDB is connected before any database operations are performed.

Step 6: Define Mongoose Schema

Let’s define a simple schema for User using Mongoose. Create a User model under the lib/models directory.

/lib/models/User.ts

import mongoose, { Schema, Document } from 'mongoose';

export interface IUser extends Document {
  name: string;
  email: string;
  password: string;
}

const UserSchema: Schema = new mongoose.Schema({
  name: { type: String, required: true },
  email: { type: String, required: true, unique: true },
  password: { type: String, required: true },
});

const User = mongoose.models.User || mongoose.model<IUser>('User', UserSchema);

export default User;

Explanation:

This defines the structure of a User document in MongoDB.
The schema ensures that each user has a name, email, and password, with validation to require all fields.

Conclusion
In this guide, we demonstrated how to connect MongoDB to a Next.js application using Mongoose, how to set up MongoDB Atlas, and how to efficiently manage database connections in API routes.

By following these steps, you can build scalable Next.js applications that work seamlessly with MongoDB.

How to Set Up MongoDB with Next.js