Overview
En esta guía, puedes aprender cómo crear una aplicación web con Next.js que se integra con MongoDB. Next.js es un framework de React que proporciona renderización del lado del servidor, generación de sitios estáticos y rutas de API en una sola aplicación. La aplicación en este tutorial consiste en las siguientes capas:
Capa de base de datos: MongoDB proporciona almacenamiento y recuperación de datos.
Capa API: las rutas API de Next.js gestionan la lógica del lado del servidor y las operaciones de base de datos.
Capa de presentación: Los componentes de React implementan la interfaz de usuario y las interacciones del front-end.
¿Por qué usar MongoDB en una aplicación Next.js?
Next.js es un framework full-stack de React que te permite construir tanto el frontend como el backend de tu aplicación en una única base de código. Al integrar MongoDB con Next.js, puedes aprovechar los siguientes beneficios:
Desarrollo unificado: Escribe tanto el código del cliente como del servidor en JavaScript/TypeScript
Renderizado del lado del servidor: Obtén datos de MongoDB durante el renderizado del lado del servidor para mejorar el SEO y el rendimiento
Rutas de API: crea endpoints API sin servidor que se conecten directamente a MongoDB
Modelo de datos flexible: El modelo orientado a documentos de MongoDB se alinea de forma natural con los objetos de JavaScript y el estado de los componentes de React
Next.js con MongoDB es una combinación ideal para aplicaciones que requieren contenido dinámico, autenticación de usuarios, actualizaciones en tiempo real y relaciones de datos complejas.
Tutorial de inicio rápido
Este tutorial muestra cómo compilar una aplicación web usando Next.js y MongoDB. La aplicación accede a una muestra de datos de restaurantes, hace query los datos y muestra los resultados en un sitio hosteado localmente. El tutorial también incluye instrucciones para conectarse a un clúster de MongoDB alojado en MongoDB Atlas, acceder y mostrar datos de su base de datos.
Tip
Si prefieres conectarte a MongoDB utilizando el controlador de Node.js sin Next.js, ver el Guía Comenzar con el driver de Node.js.
Configurar el proyecto
Siga los pasos de esta sección para instalar las dependencias del proyecto, crear un clúster de Atlas y configurar los directorios de la aplicación.
Verifique los requisitos previos
Para crear la aplicación, necesitas tener instalado lo siguiente en tu entorno de desarrollo:
Requisito previo | notas |
|---|---|
Descarga la versión LTS más reciente o versión más reciente. | |
Editor de código | Este tutorial utiliza Visual Studio Code, pero puede utilizar el editor de su preferencia. |
Aplicación de terminal o shell | Para los usuarios de MacOS, use Terminal o una aplicación similar. Para usuarios de Windows, utilizar PowerShell. |
Crea un clúster de MongoDB Atlas
MongoDB Atlas es un servicio de base de datos en la nube completamente gestionado que aloja tus implementaciones de MongoDB. Si no tienes una implementación de MongoDB, puedes crear un clúster de MongoDB de forma gratuita (no se requiere tarjeta de crédito) completando el tutorial Introducción a MongoDB. El tutorial Get Started de MongoDB también demuestra cómo cargar conjuntos de datos de muestra en tu clúster, incluido el sample_restaurants base de datos que se emplea en este tutorial.
Para conectarte a tu clúster de MongoDB, debes usar un URI de conexión. Para saber cómo recuperar tu URI de conexión, consulta la sección Agrega tu cadena de conexión del tutorial Primeros pasos de MongoDB.
Importante
Guarda tu cadena de conexión en una ubicación segura.
Cree su aplicación de Next.js
Ejecuta el siguiente comando en tu terminal para crear una nueva aplicación Next.js.
npx create-next-app@latest next-quickstart
El comando te indica seleccionar algunas opciones de configuración para tu proyecto. Cuando se le indique, selecciona la opción por defecto recomendada.
Después de ejecutar el comando, navega al directorio del proyecto:
cd next-quickstart
Configura la conexión a la base de datos
Después de configurar la estructura del proyecto y las dependencias, sigue los pasos de esta sección para configurar tu conexión a la base de datos.
Establecer variables de entorno
En el directorio next-quickstart, crea un archivo .env.local que almacene tu URI de conexión de MongoDB:
MONGODB_URI=<connection URI>
Reemplaza el marcador de posición <connection URI> con el URI de conexión que guardaste en un paso anterior.
Nota
Next.js carga automáticamente las variables de entorno desde los archivos .env.local. Las variables que tienen el prefijo NEXT_PUBLIC_ se exponen al navegador, mientras que las demás variables solo están disponibles en el servidor.
Crear la utilidad de conexión de base de datos
En el directorio raíz, crea un nuevo directorio llamado lib. Agrega un nuevo archivo llamado mongodb.ts a este directorio y pega el siguiente 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;
Este archivo crea una conexión de cliente MongoDB reutilizable que se comparte en toda su aplicación. La conexión se almacena en caché para evitar la creación de múltiples conexiones durante el desarrollo, cuando Next.js recarga tu código en caliente.
Crear rutas de API
Después de configurar la conexión a la base de datos, sigue los pasos de esta sección para crear rutas API que consulten la query MongoDB y devuelvan datos de restaurantes.
Crear la ruta API del restaurante
En el directorio app, crea un nuevo directorio api/restaurants. Agrega un nuevo archivo llamado route.ts a este directorio y pega el siguiente 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 archivo define un endpoint GET en /api/restaurants que recupera todos los restaurantes de la base de datos sample_restaurants.
Crear la API de ruta de navegación
En el directorio app/api, crea un nuevo directorio llamado browse. Crea un nuevo archivo llamado route.ts en este directorio y pega el siguiente 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 archivo define un endpoint de GET en /api/browse que recupera restaurantes que coinciden con criterios de query específicos. El filtro de query para restaurantes en Queens que contengan la palabra "Moon" en el nombre.
Configure el Front End
Una vez que configures las rutas de la API, sigue los pasos de esta sección para crear las componentes de React que muestran los datos del restaurante.
Crear el componente Navbar
En el directorio raíz, crea un nuevo directorio llamado components. Agrega un nuevo archivo llamado Navbar.tsx a este directorio y pega el siguiente 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 crea una barra de navegación con enlaces para ver todos los restaurantes y restaurantes filtrados.
Crea el componente RestaurantList
En el directorio components, crea un archivo nuevo llamado RestaurantList.tsx y pega el siguiente 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 recupera y muestra los datos del restaurante desde las rutas de la API. Utiliza los hooks de React para gestionar el estado y obtener datos cuando el componente se monta.
Actualiza la página de inicio
Navega al archivo app/page.tsx y reemplaza el contenido con el siguiente 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 archivo renderiza la página de inicio, que detalla todos los restaurantes de la base de datos.
Cree la página de exploración
En el directorio app, crea un nuevo directorio llamado browse. Agregue un nuevo archivo llamado page.tsx a este directorio y pegue el siguiente 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 archivo renderiza la página de búsqueda, que muestra restaurantes filtrados según los criterios de query.
Actualizar el diseño
Navega al archivo app/layout.tsx y reemplaza el contenido con el siguiente 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> ); }
Este archivo define la disposición principal de tu aplicación, que incluye la barra de navegación y engloba todas las páginas.
Ejecutar la aplicación
Por último, sigue los pasos de esta sección para ejecutar la aplicación y ver los datos del restaurante renderizados.
Iniciar el servidor de desarrollo
Navegue hasta el directorio next-quickstart y ejecute el siguiente comando para iniciar el servidor de desarrollo de Next.js:
npm run dev
Si es exitoso, este comando muestra la siguiente información:
▲ Next.js 15.1.6 - Local: http://localhost:3000 ✓ Starting... ✓ Ready in 2.3s
Abre el sitio de la aplicación
Abra el http://localhost:3000/ URL. La página de aterrizaje inicial muestra una lista de todos los restaurantes en la colección sample_restaurants.restaurants:

Haz clic en Filtered Restaurants enlace en la barra de navegación para ver los restaurantes que coinciden con la query de los campos name y borough.

¡Felicidades por completar el tutorial de inicio rápido!
Después de completar estos pasos, tendrás una aplicación web Next.js que se conecta a tu implementación de MongoDB, ejecuta consultas sobre datos de muestra de restaurantes y renderiza los resultados en un sitio web hosteado localmente.
Recursos adicionales
Para obtener más información sobre Next.js y MongoDB, consulta los siguientes recursos:
Documentación del controlador Node.js
documentación de Next.js
Documentación Rutas de la API de Next.js