How to Integrate MongoDB Into Your Next.js App

#Example 1: Next.js API Endpoint with MongoDB

The first example we'll look at is building and exposing an API endpoint in our Next.js application. To create a new API endpoint route we will first need to create an api directory in our pages directory, and then every file we create in this api directory will be treated as an individual API endpoint.

Let's go ahead and create the api directory and a new file in this directory called movies.js. This endpoint will return a list of 20 movies from our MongoDB database. The implementation for this route is as follows:

1
import { connectToDatabase } from "../../util/mongodb";
2
3
export default async (req, res) => {
4
  const { db } = await connectToDatabase();
5
6
  const movies = await db
7
    .collection("movies")
8
    .find({})
9
    .sort({ metacritic: -1 })
10
    .limit(20)
11
    .toArray();
12
13
  res.json(movies);
14
};

To explain what is going on here we'll start with the import statement. We are importing our connectToDatabase method from the util/mongodb file. This file contains all the instructions on how to connect to our MongoDB Atlas cluster. Additionally, within this file we cache the instance of our connection so that subsequent requests do not have to reconnect to the cluster. They can use the existing connection. All of this is handled for you!

Next our API route handler has the signature of export default async (req, res). If you're familiar with Express.js, this should look very familiar. This is the function that gets executed when the localhost:3000/api/movies route is called. We capture the request via req and return the response via the res object.

Our handler function implementation calls the connectToDatabase() function to get the instance of our MongoDB database. Next, we execute a MongoDB query using the MongoDB Node.js Driver to get the top twenty movies out of our movies collection based on their metacritic rating sorted in descending order.

Finally, we call the res.json method and pass in our array of movies. This serves our movies in JSON format to our browser. If we navigate to localhost:3000/api/movies, we'll see a result that looks like this:

We can add additional API routes by creating additional files in the api directory. As a homework exercise, why don't you create an API route that returns a single movie based on a user provided id?

To give you some pointers, you'll use Next.js Dynamic API Routes to capture the id. So if a user calls http://localhost:3000/api/movies/573a1394f29313caabcdfa3e the movie that should be returned is Seven Samurai. Another tip, the _id property for the sample_mflix database in MongoDB is stored as an ObjectID, so you'll have to convert the string to an ObjectID. If you get stuck, create a thread on the MongoDB Community forums and we'll solve it together! Next, we'll take a look at how to access our MongoDB data within our Next.js pages.

#Example 2: Next.js Pages with MongoDB

In the last section, we saw how we can create an API endpoint and connect to MongoDB with it. In this section, we'll get our data directly into our Next.js pages. We'll do this using the getServerSideProps() method that is available to Next.js pages.

The getServerSideProps() method forces a Next.js page to load with server-side rendering. What this means is that every time this page is loaded, the getServerSideProps() method runs on the backend, gets data, and sends it into the React component via props. The code within getServerSideProps() is never sent to the client. This makes it a great place to implement our MongoDB queries.

Let's see how this works in practice. Let's create a new file in the pages directory, and we'll call it movies.js. In this file, we'll add the following code:

1
import { connectToDatabase } from "../util/mongodb";
2
3
export default function Movies({ movies }) {
4
  return (
5
    <div>
      <h1>Top 20 Movies of All Time</h1>
      <p>
        <small>(According to Metacritic)</small>
      </p>
      <ul>
        {movies.map((movie) => (
          <li>
            <h2>{movie.title}</h2>
            <h3>{movie.metacritic}</h3>
            <p>{movie.plot}</p>
          </li>
        ))}
      </ul>
    </div>
6
  );
7
}
8
9
export async function getServerSideProps() {
10
  const { db } = await connectToDatabase();
11
12
  const movies = await db
13
    .collection("movies")
14
    .find({})
15
    .sort({ metacritic: -1 })
16
    .limit(20)
17
    .toArray();
18
19
  return {
20
    props: {
21
      movies: JSON.parse(JSON.stringify(movies)),
22
    },
23
  };
24
}

As you can see from the example above, we are importing the same connectToDatabase utility class, and our MongoDB query is exactly the same within the getServerSideProps() method. The only thing we really needed to change in our implementation is how we parse the response. The getServerSideProps() return method has some trouble serializing our data. There is a GitHub issue open to address this, but the current workaround is to stringify and then parse the data manually.

Our page component called Movies gets the props from our getServerSideProps() method, and we use that data to render the page showing the top movie title, metacritic rating, and plot. Your result should look something like this:

This is great. We can directly query our MongoDB database and get all the data we need for a particular page. The contents of the getServerSideProps() method are never sent to the client, but the one downside to this is that this method runs every time we call the page. Our data is pretty static and unlikely to change all that often. What if we pre-rendered this page and didn't have to call MongoDB on every refresh? We'll take a look at that next!

#Example 3: Next.js Static Generation with MongoDB

For our final example, we'll take a look at how static page generation can work with MongoDB. Let's create a new file in the pages directory and call it top.js. For this page, what we'll want to do is render the top 1000 movies from our MongoDB database.

Top 1000 movies? Are you out of your mind? That'll take a while, and the database round trip is not worth it. Well what if we only called this method once when we built the application, so that even if that call takes a few seconds, it'll only ever happen once and our users won't be affected. They'll get the top 1000 movies delivered as quickly or even faster than the 20 using serverSideProps(). The magic lies in the getStaticProps() method, and our implementation looks like this:

1
import { connectToDatabase } from "../util/mongodb";
2
3
export default function Top({ movies }) {
4
  return (
5
    <div>
      <h1>Top 1000 Movies of All Time</h1>
      <p>
        <small>(According to Metacritic)</small>
      </p>
      <ul>
        {movies.map((movie) => (
          <li>
            <h2>{movie.title}</h2>
            <h3>{movie.metacritic}</h3>
            <p>{movie.plot}</p>
          </li>
        ))}
      </ul>
    </div>
6
  );
7
}
8
9
export async function getStaticProps() {
10
  const { db } = await connectToDatabase();
11
12
  const movies = await db
13
    .collection("movies")
14
    .find({})
15
    .sort({ metacritic: -1 })
16
    .limit(1000)
17
    .toArray();
18
19
  return {
20
    props: {
21
      movies: JSON.parse(JSON.stringify(movies)),
22
    },
23
  };
24
}

At a glance this looks very similar to the movies.js file we created earlier. The only significant changes we made were changing our limit from 20 to 1000 and our getServerSideProps() method to getStaticProps(). If we navigate to localhost:3000/top in our browser, we'll see a long list of movies.

Look at how tiny that scrollbar is. Loading this page took about 3.5 seconds on my machine as opposed to sub-1 second response time for the /movies page. The reason it takes this long is because in development mode the getStaticProps() method is called every single time (just like the getServerSideProps() method). But if we switch from development mode to production mode, we'll see the opposite. The /top page will be pre-rendered and will load almost immediately, while the /movies and /api/movies routes will execute the server-side code each time.

Let's switch to production mode. In your terminal window stop the current app from running. To run our Next.js app in production mode we'll first need to build it, then we can run the start command which will serve our built application. In your terminal window execute the following commands:

1
npm run build
2
npm run start

When you run the npm run start command, your Next.js app is served in production mode. The getStaticProps() method will not be executed every time you hit the /top route as this page will now be served statically. We can even see the pre-rendered static page by navigating to the .next/server/pages/top.html file and seeing the 1,000 movies listed in plain HTML.

Next.js can even update this static content without requiring a rebuild with a feature called Incremental Static Regeneration, but that's outside of the scope of this tutorial. Next, we'll take a look at deploying our application on Vercel.