Como integrar MongoDB com Next.js: tutorial passo a passo

Para integrar o MongoDB com Next.js, use o exemplo oficial with-mongodb: rode npx create-next-app --example with-mongodb, defina a variável MONGODB_URI com a string de conexão do MongoDB Atlas e consulte os dados por rotas de API. Este guia cobre tudo, do zero ao deploy na Vercel.

• O que você precisa para integrar Next.js e MongoDB?
• O que é Next.js?
• O que é MongoDB?
• Como criar um projeto Next.js com MongoDB?
• Como conectar o MongoDB ao Next.js?
• Como consultar dados do MongoDB no Next.js?
• Exemplo prático: endpoint de API do Next.js com MongoDB
• Enviando o projeto Next.js para o GitHub
• Como fazer deploy do projeto na Vercel?
• Next.js e MongoDB com um clique

🗒️ Nota: Este tutorial usa o Next.js Pages Router em vez do App Router, introduzido no Next.js 13. O Pages Router continua compatível e recomendado para ambientes de produção.

O que você precisa para integrar Next.js e MongoDB?

Para seguir este tutorial, você precisa de quatro coisas: uma conta no MongoDB Atlas, uma conta na Vercel, o Node.js 18 ou superior e o gerenciador de pacotes npm (com o npx). Todos têm nível gratuito, então dá para concluir a integração sem gastar nada.

• MongoDB Atlas (cadastro gratuito)
• Conta na Vercel (cadastro gratuito)
• Node.js 18+
• npm e npx

Para aproveitar ao máximo o conteúdo, é recomendável ter familiaridade com React e Next.js. Mesmo assim, abordamos os recursos exclusivos com detalhe suficiente para que iniciantes também tirem valor deste guia aqui no CodeCrush.

O que é Next.js?

O Next.js é um framework baseado em React para construir aplicações web modernas. Ele adiciona recursos poderosos como renderização no lado do servidor (SSR), divisão automática de código e regeneração estática incremental, o que facilita criar aplicações escaláveis e prontas para produção.

Esses recursos tornam o Next.js uma escolha natural para quem quer combinar frontend e backend em um único projeto Node.js, sem manter dois servidores separados.

O que é MongoDB?

O MongoDB é um sistema de gerenciamento de banco de dados NoSQL (Not Only SQL) usado para construir aplicações modernas e escaláveis. Diferente dos bancos relacionais, ele adota um modelo de dados flexível baseado em documentos JSON (JavaScript Object Notation), o que facilita armazenar e manipular dados semiestruturados e não estruturados.

O MongoDB oferece alta disponibilidade, escalabilidade horizontal e suporte a consultas poderosas, o que o torna popular em cenários que vão de aplicações web a análises de Big Data. Segundo o Stack Overflow Developer Survey 2024, o MongoDB é usado por 24,8% dos desenvolvedores, sendo o banco de dados NoSQL mais popular — atrás apenas de opções relacionais como o MySQL e o PostgreSQL, este último líder com 48,7%.

Como criar um projeto Next.js com MongoDB?

O Next.js mantém uma biblioteca extensa de exemplos que mostram como integrar o framework a diferentes funcionalidades, como servidores GraphQL, bibliotecas de autenticação e frameworks de CSS. O exemplo que usaremos se chama with-mongodb e já vem com tudo o que é necessário para conectar a um banco MongoDB.

Para criar um novo aplicativo Next.js com a integração MongoDB embutida, execute o seguinte comando no terminal:

npx create-next-app --example with-mongodb codecrush

O comando npx create-next-app recebe o parâmetro --example with-mongodb, que instrui o gerador a inicializar o app com o exemplo de integração MongoDB. O codecrush é o nome do projeto — você pode escolher outro. Após instalar as dependências do npm, Yarn ou pnpm, entre no diretório do projeto:

cd codecrush

Em algumas versões do Node superiores à 18, o download pode falhar com um erro como este:

? Could not download "with-mongodb" because of a connectivity issue between your machine and GitHub.
✔ Could not download "with-mongodb" because of a connectivity issue between your machine and GitHub.
Do you want to use the default template instead? (Y/n)

O problema está no node-tar extract(), que emite o evento close. Existe uma issue aberta no GitHub sobre isso. Para contornar, use uma versão do Node inferior à 18 ou digite Y para baixar o modelo padrão:

Do you want to use the default template instead? (Y/n) Y

Em seguida, instale as dependências e inicie o servidor de desenvolvimento no diretório do projeto:

npm install
npm run dev

Depois que o app subir, acesse localhost:3000. Você verá um erro — e isso é esperado. 😱

A boa notícia é que o erro é descritivo: ele acontece porque ainda não fornecemos a string de conexão do MongoDB ao aplicativo Next.js. Vamos resolver isso na próxima seção.

Como conectar o MongoDB ao Next.js?

O MongoDB se conecta ao Next.js através da variável de ambiente MONGODB_URI. No diretório do projeto existe um arquivo env.local.example: renomeie-o para env.local e preencha a propriedade MONGODB_URI com a string de conexão do seu cluster no MongoDB Atlas.

Você pode usar uma instalação local do MongoDB, mas o MongoDB Atlas é o caminho mais rápido para começar sem gerenciar sua própria instância. O nível gratuito M0 do Atlas oferece 512 MB de armazenamento e até 500 conexões simultâneas, conforme a documentação de limites do MongoDB Atlas — de sobra para os dados de amostra deste tutorial.

Para obter a URI (Uniform Resource Identifier), no painel do Atlas clique em Connect e depois em Connect to your application. A string terá este formato:

mongodb+srv://<USERNAME>:<PASSWORD>@cluster0.vyllhkl.mongodb.net/<DBNAME>?retryWrites=true&w=majority

Se você é novo no Atlas, vá até Database Access e crie um usuário com senha, e a Network Access para garantir que seu IP esteja autorizado. Se já tem usuário e acesso de rede, basta substituir <USERNAME> e <PASSWORD> pelas suas credenciais.

Para o <DBNAME>, carregue os conjuntos de dados de amostra do Atlas: sob o cluster escolhido, clique no botão ... e selecione Load Sample Dataset. O carregamento leva alguns minutos e cria vários bancos. Usaremos o sample_codecrush, então defina o <DBNAME> para esse valor.

Ao final, o arquivo env.local deve ficar assim:

MONGODB_URI=mongodb+srv://<USERNAME>:<PASSWORD>@codecrush.sdgqrsd.mongodb.net/?retryWrites=true&w=majority

Reinicie a aplicação com npm run dev e acesse localhost:3000. Se aparecer a mensagem "You are connected to MongoDB", está tudo certo. Se aparecer "You are NOT connected to MongoDB", revise a string de conexão, o usuário do banco e o acesso de rede. Em caso de dúvida, os fóruns da comunidade MongoDB costumam ter a solução.

Como consultar dados do MongoDB no Next.js?

O Next.js oferece várias formas de buscar dados do MongoDB depois que a conexão está ativa. Você pode criar rotas de API, executar funções renderizadas no servidor com getServerSideProps para uma página específica, ou gerar páginas estáticas com getStaticProps, buscando os dados no momento do build.

Cada abordagem serve a um cenário: rotas de API expõem um endpoint reutilizável, getServerSideProps renderiza sob demanda a cada requisição e getStaticProps pré-renderiza no build para máxima performance. A seguir, vamos ao exemplo mais comum: a rota de API.

Exemplo prático: endpoint de API do Next.js com MongoDB

Uma rota de API (Application Programming Interface) no Next.js é qualquer arquivo dentro do diretório pages/api. Cada arquivo vira um endpoint individual. Vamos criar o diretório api dentro de pages e, nele, um arquivo languages.js que retorna uma lista de linguagens de programação do banco MongoDB:

import clientPromise from "../../lib/mongodb";

export default async (req, res) => {
   try {
       const client = await clientPromise;
       const db = client.db("codecrush");

       const languages = await db
           .collection("languages")
           .find({})
           .sort({ year: -1 })
           .limit(10)
           .toArray();

       res.json(languages);
   } catch (e) {
       console.error(e);
   }
};

Começando pela importação: trazemos o método clientPromise do arquivo lib/mongodb, que contém as instruções para conectar ao cluster do Atlas. Esse arquivo também guarda a instância de conexão em cache, para que requisições seguintes reaproveitem a conexão existente em vez de reconectar ao cluster — tudo tratado automaticamente para você.

O manipulador de rota tem a assinatura export default async (req, res). Se você já usou Express.js, isso parecerá familiar. Essa função roda quando a rota localhost:3000/api/languages é chamada: capturamos a requisição via req e devolvemos a resposta via res.

A função chama clientPromise para obter a instância do banco e executa uma consulta com o driver Node.js do MongoDB, retornando as 10 linguagens mais recentes da coleção languages, ordenadas por ano em ordem decrescente. Por fim, res.json entrega o array em formato JSON. Ao navegar para localhost:3000/api/languages, o resultado será parecido com este:

[
  {
    "_id": "573a1394f29313caabcdfa3e",
    "name": "Dirt",
    "category": "Linguagem de Programação",
    "year": 2023,
    "creator": "John Doe",
    "description": "Dirt é uma linguagem de programação versátil projetada para desenvolvimento rápido e facilidade de uso. Ela ganhou popularidade por sua simplicidade e recursos poderosos.",
    "website": "https://dirtlang.com"
  },
  {
    "_id": "573a1394f29313caabcdfa3f",
    "name": "Sparkle",
    "category": "Linguagem de Programação",
    "year": 2024,
    "creator": "Jane Smith",
    "description": "Sparkle é uma linguagem de alto desempenho otimizada para processamento e análise de dados. Ela oferece integração perfeita com estruturas de computação distribuída.",
    "website": "https://sparklelang.org"
  },
  {
    "_id": "573a1394f29313caabcdfa40",
    "name": "Glimmer",
    "category": "Linguagem de Programação",
    "year": 2022,
    "creator": "Maxwell Johnson",
    "description": "Glimmer é uma linguagem moderna conhecida por sua sintaxe elegante e suporte à concorrência. É adequada para construir sistemas escaláveis e tolerantes a falhas.",
    "website": "https://glimmerlang.io"
  }
]

Você pode adicionar novas rotas criando mais arquivos no diretório api. Como exercício, que tal criar uma rota que retorne uma única linguagem a partir de um ID informado pelo usuário? Use as rotas de API dinâmicas do Next.js para capturar o ID.

Assim, ao chamar http://localhost:3000/api/language/573a1394f29313caabcdfa3e, a linguagem retornada deve ser Dirt. Uma dica: no banco sample_codecrush, a propriedade _id é armazenada como um ObjectID, então você precisará converter a string para ObjectID antes da consulta.

Enviando o projeto Next.js para o GitHub

Com o projeto funcionando, é hora de versioná-lo no GitHub. Siga estes passos, começando cada comando no terminal, dentro do diretório do projeto:

1. Inicialize um repositório Git local com git init.
2. Adicione todos os arquivos ao próximo commit com git add ..
3. Confirme as mudanças com uma mensagem descritiva: git commit -m "Primeiro commit".
4. Conecte o repositório local ao remoto: git remote add origin URL_do_repositorio, substituindo URL_do_repositorio pelo endereço do seu repositório no GitHub.
5. Envie os commits para o GitHub com git push origin main.
6. Acesse o repositório no GitHub e confirme que os arquivos foram enviados.

Caso ainda não tenha criado o repositório, siga o guia oficial do GitHub.

Esses são os passos básicos para enviar o código quando você já tem o Git configurado na máquina e uma conta no GitHub. Adapte-os conforme o fluxo de trabalho do seu projeto.

Como fazer deploy do projeto na Vercel?

O deploy do projeto Next.js com MongoDB é feito importando o repositório na Vercel. Acesse o painel da Vercel, clique em Add New Project e depois em Import Git Repository, escolhendo o repositório que você acabou de enviar ao GitHub.

Na tela seguinte, expanda Environment Variables e adicione a variável MONGODB_URI com o valor do seu arquivo env.local. Confirme o valor antes de prosseguir.

Ao clicar em Deploy, a Vercel constrói e publica a aplicação automaticamente. Em alguns minutos você recebe uma URL de produção. Se preferir um provedor com controle sobre a infraestrutura, veja também nosso guia sobre servidores e o universo AWS.

🗒️ Nota: A Vercel usa endereços IP dinâmicos, então libere o acesso de qualquer IP no MongoDB Atlas. Vá até Network Access, clique em Add IP Address e escolha Allow Access From Anywhere (ou informe 0.0.0.0/0).

Next.js e MongoDB com um clique

Se você não acompanhou o passo a passo e quer subir rapidamente uma aplicação Next.js com MongoDB, dá para usar o starter with-mongodb no GitHub. Há, porém, um caminho ainda mais direto.

Este link de deploy clona o exemplo oficial e o publica na Vercel — você só precisa fornecer a sua string de conexão.

Conclusão

Integrar MongoDB e Next.js é surpreendentemente rápido quando você parte do exemplo oficial with-mongodb: em poucos minutos o app está conectado, consultando dados por rotas de API e implantado na Vercel. O que faz essa combinação escalar bem em produção é a conexão em cache do arquivo lib/mongodb — ela evita esgotar as conexões do cluster no ambiente serverless. Comece pelo cluster gratuito M0, valide sua ideia sem custo e só migre para um cluster dedicado quando o tráfego justificar. Se tiver dúvidas, os fóruns da comunidade MongoDB são um ótimo ponto de apoio.