Next.js MongoDB Integration

Introduction

MongoDB is a popular NoSQL database that works exceptionally well with JavaScript-based applications like those built with Next.js. This integration allows developers to create powerful full-stack applications with efficient data storage and retrieval capabilities.

In this guide, we'll explore how to connect a Next.js application to MongoDB, perform CRUD (Create, Read, Update, Delete) operations, and implement best practices for production-ready applications.

Why MongoDB with Next.js?

MongoDB offers several advantages when paired with Next.js:

JSON-like document structure: MongoDB stores data in BSON format, which aligns perfectly with JavaScript's native objects
Schema flexibility: Perfect for rapidly evolving applications
Scalability: Easy to scale horizontally as your application grows
Rich query API: Powerful querying capabilities
Native support for JavaScript: Works seamlessly with Node.js environments

Prerequisites

Before we start, ensure you have:

Basic knowledge of Next.js
Node.js installed on your machine
MongoDB Atlas account (or local MongoDB installation)
npm or yarn package manager

Setting Up MongoDB for Next.js

Step 1: Install Required Packages

First, let's install the necessary packages:

bash
npm install mongodb
# or
yarn add mongodb

Step 2: Create a MongoDB Connection Utility

Create a utility file to manage your MongoDB connection. This approach prevents multiple connections from being created when your application hot-reloads during development.

Create a file named lib/mongodb.js:

javascript
import { MongoClient } from 'mongodb';

const uri = process.env.MONGODB_URI;
const options = {
  useUnifiedTopology: true,
  useNewUrlParser: true,
};

let client;
let clientPromise;

if (!process.env.MONGODB_URI) {
  throw new Error('Please add your MongoDB URI to .env.local');
}

if (process.env.NODE_ENV === 'development') {
  // In development mode, use a global variable to preserve the connection across hot-reloads
  if (!global._mongoClientPromise) {
    client = new MongoClient(uri, options);
    global._mongoClientPromise = client.connect();
  }
  clientPromise = global._mongoClientPromise;
} else {
  // In production mode, it's best to not use a global variable
  client = new MongoClient(uri, options);
  clientPromise = client.connect();
}

export default clientPromise;

Step 3: Configure Environment Variables

Create a .env.local file in the root of your project and add your MongoDB connection string:

MONGODB_URI=mongodb+srv://<username>:<password>@<cluster-url>/<database>?retryWrites=true&w=majority

Make sure to replace <username>, <password>, <cluster-url>, and <database> with your actual MongoDB credentials.

Basic CRUD Operations with Next.js API Routes

Let's implement basic CRUD operations using Next.js API routes.

Creating a Document

Create a file pages/api/create-post.js:

javascript
import clientPromise from '../../lib/mongodb';

export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ message: 'Method not allowed' });
  }

  try {
    const { title, content, author } = req.body;
    
    // Input validation
    if (!title || !content || !author) {
      return res.status(400).json({ message: 'Missing required fields' });
    }
    
    const client = await clientPromise;
    const db = client.db('blog');
    
    const post = {
      title,
      content,
      author,
      createdAt: new Date(),
    };
    
    const result = await db.collection('posts').insertOne(post);
    
    res.status(201).json({
      message: 'Post created successfully',
      postId: result.insertedId,
    });
  } catch (error) {
    console.error(error);
    res.status(500).json({ message: 'Error creating post', error: error.message });
  }
}

Reading Documents

Create a file pages/api/get-posts.js:

javascript
import clientPromise from '../../lib/mongodb';

export default async function handler(req, res) {
  try {
    const client = await clientPromise;
    const db = client.db('blog');
    
    // Get all posts, sorted by creation date
    const posts = await db
      .collection('posts')
      .find({})
      .sort({ createdAt: -1 })
      .toArray();
    
    res.status(200).json(posts);
  } catch (error) {
    console.error(error);
    res.status(500).json({ message: 'Error retrieving posts', error: error.message });
  }
}

Updating a Document

Create a file pages/api/update-post.js:

javascript
import clientPromise from '../../lib/mongodb';
import { ObjectId } from 'mongodb';

export default async function handler(req, res) {
  if (req.method !== 'PUT') {
    return res.status(405).json({ message: 'Method not allowed' });
  }

  try {
    const { id, title, content, author } = req.body;
    
    // Input validation
    if (!id || (!title && !content && !author)) {
      return res.status(400).json({ message: 'Invalid update data' });
    }
    
    const client = await clientPromise;
    const db = client.db('blog');
    
    // Create update object with only the provided fields
    const updateData = {};
    if (title) updateData.title = title;
    if (content) updateData.content = content;
    if (author) updateData.author = author;
    updateData.updatedAt = new Date();
    
    const result = await db.collection('posts').updateOne(
      { _id: new ObjectId(id) },
      { $set: updateData }
    );
    
    if (result.matchedCount === 0) {
      return res.status(404).json({ message: 'Post not found' });
    }
    
    res.status(200).json({
      message: 'Post updated successfully',
      modifiedCount: result.modifiedCount,
    });
  } catch (error) {
    console.error(error);
    res.status(500).json({ message: 'Error updating post', error: error.message });
  }
}

Deleting a Document

Create a file pages/api/delete-post.js:

javascript
import clientPromise from '../../lib/mongodb';
import { ObjectId } from 'mongodb';

export default async function handler(req, res) {
  if (req.method !== 'DELETE') {
    return res.status(405).json({ message: 'Method not allowed' });
  }

  try {
    const { id } = req.body;
    
    if (!id) {
      return res.status(400).json({ message: 'Post ID is required' });
    }
    
    const client = await clientPromise;
    const db = client.db('blog');
    
    const result = await db.collection('posts').deleteOne({
      _id: new ObjectId(id),
    });
    
    if (result.deletedCount === 0) {
      return res.status(404).json({ message: 'Post not found' });
    }
    
    res.status(200).json({
      message: 'Post deleted successfully',
    });
  } catch (error) {
    console.error(error);
    res.status(500).json({ message: 'Error deleting post', error: error.message });
  }
}

Server-Side Rendering with MongoDB Data

One of Next.js's key features is server-side rendering. Let's see how to fetch data from MongoDB and render it on the server side:

Create a file pages/posts/index.js:

jsx
import clientPromise from '../../lib/mongodb';
import Head from 'next/head';
import Link from 'next/link';
import styles from '../../styles/Posts.module.css';

export default function Posts({ posts }) {
  return (
    <div className={styles.container}>
      <Head>
        <title>Blog Posts</title>
      </Head>

      <main className={styles.main}>
        <h1 className={styles.title}>Blog Posts</h1>

        <div className={styles.grid}>
          {posts.map((post) => (
            <div key={post._id} className={styles.card}>
              <h2>{post.title}</h2>
              <p>By: {post.author}</p>
              <p>{post.content.substring(0, 100)}...</p>
              <Link href={`/posts/${post._id}`}>
                <a>Read more &rarr;</a>
              </Link>
            </div>
          ))}
        </div>
      </main>
    </div>
  );
}

export async function getServerSideProps() {
  try {
    const client = await clientPromise;
    const db = client.db('blog');

    const posts = await db
      .collection('posts')
      .find({})
      .sort({ createdAt: -1 })
      .toArray();

    return {
      props: {
        posts: JSON.parse(JSON.stringify(posts)),
      },
    };
  } catch (error) {
    console.error(error);
    return {
      props: { posts: [] },
    };
  }
}

Note the use of JSON.parse(JSON.stringify(posts)) which is needed to serialize MongoDB documents that may contain special types like ObjectId and Date.

Using MongoDB with Next.js Static Site Generation

Next.js also supports Static Site Generation (SSG). Here's how to fetch MongoDB data at build time:

Create a file pages/posts/[id].js:

jsx
import clientPromise from '../../lib/mongodb';
import { ObjectId } from 'mongodb';
import Head from 'next/head';
import styles from '../../styles/Post.module.css';

export default function Post({ post }) {
  if (!post) {
    return <div>Loading...</div>;
  }

  return (
    <div className={styles.container}>
      <Head>
        <title>{post.title}</title>
      </Head>

      <main className={styles.main}>
        <h1 className={styles.title}>{post.title}</h1>
        <p className={styles.author}>By: {post.author}</p>
        <div className={styles.date}>
          {new Date(post.createdAt).toLocaleDateString()}
        </div>
        <div className={styles.content}>{post.content}</div>
      </main>
    </div>
  );
}

export async function getStaticPaths() {
  const client = await clientPromise;
  const db = client.db('blog');
  const posts = await db.collection('posts').find({}, { projection: { _id: 1 } }).toArray();

  const paths = posts.map((post) => ({
    params: { id: post._id.toString() },
  }));

  return { paths, fallback: true };
}

export async function getStaticProps({ params }) {
  try {
    const client = await clientPromise;
    const db = client.db('blog');
    const post = await db.collection('posts').findOne({
      _id: new ObjectId(params.id),
    });

    return {
      props: {
        post: JSON.parse(JSON.stringify(post)),
      },
      revalidate: 60, // Regenerate page every 60 seconds if needed
    };
  } catch (error) {
    console.error(error);
    return {
      notFound: true,
    };
  }
}

Building a Complete Form Example

Let's create a form to add new posts to our MongoDB database:

Create a file pages/create.js:

jsx
import { useState } from 'react';
import { useRouter } from 'next/router';
import Head from 'next/head';
import styles from '../styles/CreatePost.module.css';

export default function CreatePost() {
  const [title, setTitle] = useState('');
  const [content, setContent] = useState('');
  const [author, setAuthor] = useState('');
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [error, setError] = useState('');
  const router = useRouter();

  const handleSubmit = async (e) => {
    e.preventDefault();
    setIsSubmitting(true);
    setError('');

    try {
      const response = await fetch('/api/create-post', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ title, content, author }),
      });

      if (!response.ok) {
        const data = await response.json();
        throw new Error(data.message || 'Something went wrong');
      }

      // Redirect to posts page on success
      router.push('/posts');
    } catch (error) {
      console.error('Submission error:', error);
      setError(error.message);
    } finally {
      setIsSubmitting(false);
    }
  };

  return (
    <div className={styles.container}>
      <Head>
        <title>Create New Post</title>
      </Head>

      <main className={styles.main}>
        <h1 className={styles.title}>Create New Post</h1>

        {error && <div className={styles.error}>{error}</div>}

        <form onSubmit={handleSubmit} className={styles.form}>
          <div className={styles.formGroup}>
            <label htmlFor="title">Title:</label>
            <input
              id="title"
              type="text"
              value={title}
              onChange={(e) => setTitle(e.target.value)}
              required
            />
          </div>

          <div className={styles.formGroup}>
            <label htmlFor="author">Author:</label>
            <input
              id="author"
              type="text"
              value={author}
              onChange={(e) => setAuthor(e.target.value)}
              required
            />
          </div>

          <div className={styles.formGroup}>
            <label htmlFor="content">Content:</label>
            <textarea
              id="content"
              value={content}
              onChange={(e) => setContent(e.target.value)}
              rows="10"
              required
            />
          </div>

          <button
            type="submit"
            disabled={isSubmitting}
            className={styles.submitButton}
          >
            {isSubmitting ? 'Submitting...' : 'Create Post'}
          </button>
        </form>
      </main>
    </div>
  );
}

Advanced MongoDB Integration

Pagination Implementation

For larger collections, implementing pagination is crucial. Here's how to add pagination to your posts API:

Create a file pages/api/get-paginated-posts.js:

javascript
import clientPromise from '../../lib/mongodb';

export default async function handler(req, res) {
  const page = parseInt(req.query.page) || 1;
  const limit = parseInt(req.query.limit) || 10;
  const skip = (page - 1) * limit;

  try {
    const client = await clientPromise;
    const db = client.db('blog');
    
    // Get posts for the current page
    const posts = await db
      .collection('posts')
      .find({})
      .sort({ createdAt: -1 })
      .skip(skip)
      .limit(limit)
      .toArray();
    
    // Get total count for pagination info
    const totalPosts = await db.collection('posts').countDocuments();
    
    res.status(200).json({
      posts,
      pagination: {
        total: totalPosts,
        page,
        limit,
        pages: Math.ceil(totalPosts / limit),
      },
    });
  } catch (error) {
    console.error(error);
    res.status(500).json({ message: 'Error retrieving posts', error: error.message });
  }
}

Implementing Text Search

MongoDB provides powerful text search capabilities. Let's implement a search API:

Create a file pages/api/search-posts.js:

javascript
import clientPromise from '../../lib/mongodb';

export default async function handler(req, res) {
  const { query } = req.query;
  
  if (!query) {
    return res.status(400).json({ message: 'Search query is required' });
  }

  try {
    const client = await clientPromise;
    const db = client.db('blog');
    
    // First, create a text index (you'd typically do this once)
    // await db.collection('posts').createIndex({ title: 'text', content: 'text' });
    
    // Perform text search
    const posts = await db
      .collection('posts')
      .find({ $text: { $search: query } })
      .project({
        score: { $meta: 'textScore' }, // Include the search relevance score
        title: 1,
        content: 1,
        author: 1,
        createdAt: 1,
      })
      .sort({ score: { $meta: 'textScore' } }) // Sort by relevance
      .toArray();
    
    res.status(200).json(posts);
  } catch (error) {
    console.error(error);
    res.status(500).json({ message: 'Error searching posts', error: error.message });
  }
}

Best Practices for MongoDB with Next.js

Connection Pooling: Use a singleton pattern for database connections as shown in our mongodb.js utility
Error Handling: Always include comprehensive error handling in your database operations
Input Validation: Validate all input data before performing database operations
Indexing: Create appropriate indexes for frequently queried fields
Pagination: Implement pagination for large collections
Data Serialization: Remember to serialize MongoDB documents before sending as props
Environment Variables: Store sensitive information like connection strings in environment variables
Rate Limiting: Implement rate limiting for database operations to prevent abuse

Common Pitfalls and Troubleshooting

BSON Types in Next.js

MongoDB uses BSON types like ObjectId and Date that don't automatically serialize to JSON. Always convert these using JSON.parse(JSON.stringify(document)) before passing as props.

Connection Issues

If you're experiencing connection issues:

Check your MongoDB connection string
Ensure your IP address is whitelisted in MongoDB Atlas
Verify network connectivity
Check for proper error handling in your connection utility

Performance Considerations

Use projection to limit fields returned by queries
Create appropriate indexes for common queries
Implement caching for frequently accessed data
Consider using MongoDB Atlas's performance advisor

Summary

In this guide, we've covered how to integrate MongoDB with Next.js applications, from basic setup to advanced features like pagination and text search. We've explored:

Setting up MongoDB connection with Next.js
Performing CRUD operations through API routes
Server-side rendering with MongoDB data
Static site generation with MongoDB data
Form handling for database operations
Advanced MongoDB features
Best practices and troubleshooting

MongoDB's document-based structure makes it a perfect match for JavaScript-based frameworks like Next.js, enabling developers to build scalable full-stack applications with minimal friction between frontend and backend data structures.

Additional Resources

Exercises

Create a blog application with comments stored in a separate MongoDB collection
Implement user authentication and associate posts with specific users
Add categories and tags to posts using MongoDB arrays and implement filtering
Create an admin dashboard to manage posts with advanced filtering and sorting options
Implement real-time updates using MongoDB Change Streams and WebSockets

If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)

Introduction​

Why MongoDB with Next.js?​

Prerequisites​

Setting Up MongoDB for Next.js​

Step 1: Install Required Packages​

Step 2: Create a MongoDB Connection Utility​

Step 3: Configure Environment Variables​

Basic CRUD Operations with Next.js API Routes​

Creating a Document​

Reading Documents​

Updating a Document​

Deleting a Document​

Server-Side Rendering with MongoDB Data​

Using MongoDB with Next.js Static Site Generation​

Building a Complete Form Example​

Advanced MongoDB Integration​

Pagination Implementation​

Implementing Text Search​

Best Practices for MongoDB with Next.js​

Common Pitfalls and Troubleshooting​

BSON Types in Next.js​

Connection Issues​

Performance Considerations​

Summary​

Additional Resources​

Exercises​