Visão geral
Neste guia, você pode aprender como criar um aplicação da web Next.js que se integra ao MongoDB. Em seguida.js é uma estrutura React que fornece renderização do lado do servidor, geração de site estático e rotas de API em um único aplicação. O aplicação neste tutorial consiste nas seguintes camadas:
Camada de banco de dados: o MongoDB fornece armazenamento e recuperação de dados.
Camada API: as rotas da API do Next.js lidam com a lógica do lado do servidor e as operações de banco de dados .
Camada de apresentação: os componentes do React implementam a interface do usuário e as interações de front-end.
Por que usar o MongoDB em um aplicativo Next.js?
Next.js é uma estrutura React de pilha completa que permite criar o front-end e o back-end do seu aplicação em uma única base de código. Ao integrar o MongoDB com o Next.js, você pode aproveitar os seguintes benefícios:
Desenvolvimento unificado: escreva código de cliente e servidor em JavaScript/TypeScript
Renderização no lado do servidor: busque dados do MongoDB durante a renderização no lado do servidor para melhorar o OO e o desempenho
Rotas de API: crie endpoints de API sem servidor que se conectem diretamente ao MongoDB
Modelo de dados flexível: o modelo de documento do MongoDB alinha-se naturalmente com os objetos JavaScript e com o estado do componente React
O Next.js com MongoDB é adequado para aplicativos que exigem conteúdo dinâmico, autenticação de usuário, atualizações em tempo real e relacionamentos de dados complexos.
Tutorial de início rápido
Este tutorial mostra como construir um aplicação da web utilizando Next.js e MongoDB. O aplicação acessa dados de restaurantes de amostra, consulta os dados e exibe os resultados em um site hospedado localmente. O tutorial também inclui instruções para se conectar a um cluster MongoDB hospedado no MongoDB Atlas e acessar e exibir dados de seu banco de dados.
Dica
Se você preferir se conectar ao MongoDB usando o driver Node.js sem o Next.js, consulte o guia Introduçãoao driver Node.js
Configurar seu projeto
Siga as etapas nesta seção para instalar as dependências do projeto, criar um cluster do Atlas e configurar os diretórios do aplicativo.
Verifique os pré-requisitos
Para criar o aplicação, você precisa do seguinte instalado em seu ambiente de desenvolvimento:
Pré-requisitos | Notas |
|---|---|
Baixe a versão LTS mais recente ou a versão mais recente. | |
Editor de código | Este tutorial utiliza Visual Studio Code, mas você pode utilizar o editor de sua escolha. |
Aplicativo de terminal ou shell | Para usuários do MacOS, use o Terminal ou um aplicativo semelhante. Para usuários do Windows, use o PowerShell. |
Criar um cluster MongoDB Atlas
O MongoDB Atlas é um banco de dados em nuvem gerenciado que hospeda suas implantações do MongoDB. Se você não tiver uma implantação do MongoDB, poderá criar um cluster do MongoDB gratuitamente (nenhum cartão de crédito necessário) concluindo o tutorial MongoDB Get Started. O tutorial de Introdução ao MongoDB também demonstra como carregar conjuntos de dados de amostra em seu cluster, incluindo o banco de dados sample_restaurants usado neste tutorial.
Para se conectar ao cluster MongoDB, você deve usar um URI de conexão. Para aprender como recuperar seu URI de conexão, veja a seção Adicionar sua string de conexão do tutorial de Introdução ao MongoDB.
Importante
Salve sua string de conexão em um local seguro.
Criar seu aplicação Next.js
Execute o seguinte comando no seu terminal para criar um novo aplicação Next.js .
npx create-next-app@latest next-quickstart
O comando solicita que você selecione algumas opções de configuração para seu projeto. Quando solicitado, selecione a opção para usar os padrões recomendados.
Após executar o comando, navegue até o diretório do projeto :
cd next-quickstart
Configurar a conexão do banco de dados
Depois de configurar a estrutura e as dependências do projeto , siga as etapas desta seção para configurar sua conexão com o banco de dados .
Definir variáveis de ambiente
No diretório next-quickstart, crie um arquivo .env.local que armazena seu URI de conexão MongoDB :
MONGODB_URI=<connection URI>
Substitua o espaço reservado <connection URI> pelo URI de conexão que você salvou em uma etapa anterior.
Observação
O Next.js carrega automaticamente as variáveis de ambiente dos arquivos .env.local. As variáveis prefixadas com NEXT_PUBLIC_ estão expostas ao navegador, enquanto outras variáveis estão disponíveis somente no servidor.
Criar o utilitário de conexão do banco de dados
No diretório raiz, crie um novo diretório chamado lib. Adicione um novo arquivo denominado mongodb.ts a este diretório e cole o seguinte código:
import { MongoClient } from "mongodb"; declare global { var _mongoClientPromise: Promise<MongoClient> | undefined; } const uri = process.env.MONGODB_URI; const options = {}; let client: MongoClient; let clientPromise: Promise<MongoClient>; if (!uri) { throw new Error("Please add your Mongo URI to .env.local"); } client = new MongoClient(uri, options); clientPromise = client.connect(); // Export a module-scoped MongoClient promise. By doing this in a // separate module, the client can be shared across functions. export default clientPromise;
Esse arquivo cria uma conexão de cliente MongoDB reutilizável que é compartilhada em seu aplicação. A conexão é armazenada em cache para evitar a criação de múltiplas conexões durante o desenvolvimento quando o Next.js recarrega seu código a quente.
Criar rotas de API
Depois de configurar a conexão do banco de dados , siga as etapas nesta seção para criar rotas de API que consultam o MongoDB e retornam dados de restaurantes.
Criar a rota da API do restaurante
No diretório app, crie um novo diretório api/restaurants. Adicione um novo arquivo denominado route.ts a este diretório e cole o seguinte código:
import { NextResponse } from "next/server"; import clientPromise from "@/lib/mongodb"; export async function GET() { try { const client = await clientPromise; const db = client.db("sample_restaurants"); const restaurants = await db .collection("restaurants") .find({}) .toArray(); return NextResponse.json(restaurants); } catch { return NextResponse.json( { error: "Failed to fetch restaurants" }, { status: 500 } ); } }
Este arquivo define um endpoint GET em /api/restaurants que recupera todos os restaurantes do banco de dados sample_restaurants.
Criar a rota da API de navegação
No diretório app/api, crie um novo diretório denominado browse. Crie um novo arquivo denominado route.ts neste diretório e cole o seguinte código:
import { NextResponse } from "next/server"; import clientPromise from "@/lib/mongodb"; export async function GET() { try { const client = await clientPromise; const db = client.db("sample_restaurants"); const query = { borough: "Queens", name: { $regex: "Moon", $options: "i" }, }; const restaurants = await db .collection("restaurants") .find(query) .toArray(); return NextResponse.json(restaurants); } catch { return NextResponse.json( { error: "Failed to fetch restaurants" }, { status: 500 } ); } }
Este arquivo define um endpoint GET em /api/browse que recupera restaurantes que correspondem a critérios de query específicos. A query filtra restaurantes no Queins que contêm a palavra "Moon" no nome.
Configurar o front-end
Depois de configurar as rotas da API, siga as etapas desta seção para criar os componentes React que exibem os dados do restaurante.
Criar o componente Navbar
No diretório raiz, crie um novo diretório chamado components. Adicione um novo arquivo denominado Navbar.tsx a este diretório e cole o seguinte código:
import Link from "next/link"; export default function Navbar() { return ( <nav className="bg-gray-800 p-4"> <div className="container mx-auto flex justify-between items-center"> <Link href="/" className="text-white text-xl font-bold"> MongoDB Restaurants </Link> <div className="space-x-4"> <Link href="/" className="text-gray-300 hover:text-white transition-colors" > All Restaurants </Link> <Link href="/browse" className="text-gray-300 hover:text-white transition-colors" > Filtered Restaurants </Link> </div> </div> </nav> ); }
Este componente cria uma barra de navegação com links para visualizar todos os restaurantes e os restaurantes filtrados.
Criar o componente RestaurantList
No diretório components, crie um novo arquivo denominado RestaurantList.tsx e cole o seguinte código:
"use client"; /* The above directive tells Next.js to render this component on the client side instead of the server side. Client components can use React hooks like useState and useEffect, while server components cannot. */ import { useEffect, useState } from "react"; import { ObjectId } from "mongodb"; interface Restaurant { _id: ObjectId; name: string; borough: string; cuisine: string; } interface RestaurantProps { restaurant: Restaurant; } const Restaurant = (props: RestaurantProps) => ( <tr className="border-b transition-colors hover:bg-muted/50 data-[state=selected]:bg-muted"> <td className="p-4 align-middle [&:has([role=checkbox])]:pr-0"> {props.restaurant.name} </td> <td className="p-4 align-middle [&:has([role=checkbox])]:pr-0"> {props.restaurant.borough} </td> <td className="p-4 align-middle [&:has([role=checkbox])]:pr-0"> {props.restaurant.cuisine} </td> </tr> ); interface RestaurantListProps { endpoint: string; title: string; } export default function RestaurantList({ endpoint, title }: RestaurantListProps) { const [restaurants, setRestaurants] = useState<Restaurant[]>([]); const [loading, setLoading] = useState(true); useEffect(() => { async function getRestaurants() { try { const response = await fetch(endpoint); if (!response.ok) { const message = `An error occurred: ${response.statusText}`; console.error(message); return; } const restaurants = await response.json(); setRestaurants(restaurants); } catch (error) { console.error("Error fetching restaurants:", error); } finally { setLoading(false); } } getRestaurants(); }, [endpoint]); function restaurantList() { return restaurants.map((restaurant) => { return <Restaurant restaurant={restaurant} key={restaurant._id.toString()} />; }); } if (loading) { return <div className="p-4">Loading...</div>; } return ( <> <h3 className="text-lg font-semibold p-4">{title}</h3> <div className="border rounded-lg overflow-hidden"> <div className="relative w-full overflow-auto"> <table className="w-full caption-bottom text-sm"> <thead className="[&_tr]:border-b"> <tr className="border-b transition-colors hover:bg-muted/50 data-[state=selected]:bg-muted"> <th className="h-12 px-4 text-left align-middle font-medium text-muted-foreground [&:has([role=checkbox])]:pr-0"> Name </th> <th className="h-12 px-4 text-left align-middle font-medium text-muted-foreground [&:has([role=checkbox])]:pr-0"> Borough </th> <th className="h-12 px-4 text-left align-middle font-medium text-muted-foreground [&:has([role=checkbox])]:pr-0"> Cuisine </th> </tr> </thead> <tbody className="[&_tr:last-child]:border-0"> {restaurantList()} </tbody> </table> </div> </div> </> ); }
Este componente obtém e exibe dados de restaurantes a partir das rotas da API. Ele usa os ganchos React para gerenciar o estado e buscar dados quando o componente é montado.
Atualizar a página inicial
Navegue até o arquivo app/page.tsx e substitua o conteúdo pelo seguinte código:
import RestaurantList from "@/components/RestaurantList"; export default function Home() { return ( <main className="container mx-auto p-4"> <RestaurantList endpoint="/api/restaurants" title="All Restaurants" /> </main> ); }
Este arquivo renderiza a página inicial, que exibe todos os restaurantes do banco de dados.
Criar a página de navegação
No diretório app, crie um novo diretório denominado browse. Adicione um novo arquivo denominado page.tsx a este diretório e cole o seguinte código:
import RestaurantList from "@/components/RestaurantList"; export default function Browse() { return ( <main className="container mx-auto p-4"> <RestaurantList endpoint="/api/browse" title='Filtered Restaurants (Queens, containing "Moon")' /> </main> ); }
Este arquivo renderiza a página de navegação, que exibe restaurantes filtrados com base nos critérios da consulta.
Atualizar o layout
Navegue até o arquivo app/layout.tsx e substitua o conteúdo pelo seguinte código:
import "./globals.css"; import Navbar from "@/components/Navbar"; import { Metadata } from "next"; export const metadata: Metadata = { title: "MongoDB Next.js App", description: "A Next.js application with MongoDB integration", }; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( <html lang="en"> <body> <Navbar /> {children} </body> </html> ); }
Esse arquivo define o layout raiz do seu aplicação, que inclui a barra de navegação e envolve todas as páginas.
Execute seu aplicativo
Por fim, siga as etapas nesta seção para executar seu aplicativo e visualizar os dados renderizados do restaurante.
Iniciar o servidor de desenvolvimento
Navegue até o diretório next-quickstart e execute o seguinte comando para iniciar o servidor de desenvolvimento Next.js :
npm run dev
Se bem-sucedido, este comando gera as seguintes informações:
▲ Next.js 15.1.6 - Local: http://localhost:3000 ✓ Starting... ✓ Ready in 2.3s
Abra o site do aplicativo
Abra o http://localhost:3000/ URL. A página de destino inicial exibe uma lista de todos os restaurantes na sample_restaurants.restaurants coleção:

Clique no link Filtered Restaurants na barra de navegação para visualizar os restaurantes que correspondem à query de campo name e borough:

Parabéns por concluir o tutorial de início rápido!
Depois de concluir essas etapas, você tem um aplicação web Next.js que se conecta à implementação do MongoDB , executa queries em dados de restaurantes de exemplo e renderiza os resultados em um site hospedado localmente.
Recursos adicionais
Para saber mais sobre Next.js e MongoDB, consulte os seguintes recursos:
Documentação doNext.js
Documentaçãode rotas da API Next.js