Join us at MongoDB.local London on 7 May to unlock new possibilities for your data. Use WEB50 to save 50%.
Register now >
Docs Menu
Docs Home
/ /

Integra MongoDB con TanStack Start

Esta guía demuestra cómo compilar una aplicación web moderna con TanStack Start y MongoDB. TanStack Start es un framework full-stack que integra el desarrollo frontend y backend usando React y librerías populares como TanStack Router y TanStack Query del ecosistema TanStack.

La aplicación en este tutorial consta de las siguientes capas:

  • Capa de Base de Datos: MongoDB almacena y recupera datos.

  • Capa de servidor: TanStack Start proporciona los puntos finales de API y la lógica para conectar su interfaz a su base de datos MongoDB.

  • Capa de administración de datos: TanStack Query administra el estado del lado del servidor en el frontend, unificando la lógica para la obtención de datos, los estados de carga y el manejo de errores.

  • Capa de presentación: React implementa la interfaz de usuario utilizando los datos de TanStack Query.

El modelo de documentos de MongoDB almacena datos como documentos tipo JSON, lo que facilita el trabajo con objetos JavaScript sin necesidad de mapeos complejos. Esto se alinea con los componentes React y las interfaces TypeScript de TanStack Start.

TanStack Query gestiona la capa de datos eficientemente almacenando en caché las respuestas de MongoDB, gestionando los estados de carga y sincronizando datos entre componentes. Esto elimina la gestión manual de estados y reduce las llamadas redundantes a la base de datos.

Esta combinación funciona bien para aplicaciones que necesitan las siguientes funcionalidades:

  • Estructuras de datos flexibles que pueden evolucionar con el tiempo

  • Actualizaciones de datos en tiempo real con un mínimo de código del lado del cliente

  • Seguridad de tipos desde la base de datos a la interfaz de usuario

  • Eficiente almacenamiento en caché y sincronización de datos en segundo plano

Este tutorial te guía a través de la creación de una aplicación TanStack Start que se integra con MongoDB. La aplicación accede a datos de ejemplo de restaurantes y muestra los resultados en un sitio alojado localmente. Incluye instrucciones sobre cómo conectar tu clúster de MongoDB alojado en MongoDB Atlas y acceder y mostrar información de tu base de datos.

Tip

Si prefieres conectarte a MongoDB usando el driver de Node.js sin TanStack Start, consulta la Comiencea utilizar la guía del controlador Node.js.

Siga los pasos de esta sección para instalar las dependencias del proyecto, crear un clúster Atlas y configurar los directorios de la aplicación.

1

Para crear la aplicación de inicio rápido, asegúrate de tener el siguiente software instalado:

Requisito previo
notas

Utiliza la versión 20 o posterior.

Editor de código

Este tutorial utiliza Visual Studio Code, pero puede utilizar el editor de su preferencia.

terminal

Para usuarios de macOS, use Terminal o una aplicación similar. Para usuarios de Windows, use PowerShell.

2

MongoDB Atlas es un servicio de base de datos en la nube totalmente administrado que aloja sus implementaciones de MongoDB. Si no tiene una implementación de MongoDB, cree un clúster gratuito (no se requiere tarjeta de crédito) completando el tutorial de introducción a MongoDB. Este tutorial también muestra cómo cargar bases de datos de ejemplo en su clúster, incluyendo... sample_restaurants base de datos que se emplea en este tutorial.

Para conectarse a su clúster, debe usar una URI de conexión. Para recuperarla, siga las instrucciones del tutorial "Conectarse a su clúster" en la documentación de Atlas.

Tip

Guarda tu URI de conexión en una ubicación segura.

3

Usa la CLI oficial de TanStack Start para inicializar el esqueleto del proyecto. Abre tu terminal y navega al directorio del proyecto que desees.

Ejecuta el comando de inicialización:

npm create @tanstack/start@latest

El asistente de instalación te guía a través de la configuración. Seleccione las siguientes opciones:

Prompt
Entrada
Acción

¿Cómo deseas llamar a tu proyecto?

El nombre del proyecto que desees

Escriba el nombre y presione Enter

¿Le gustaría usar Tailwind CSS?

Teclee Y, presione Enter

Seleccione una cadena de herramientas

Predeterminado (Ninguno)

Seleccionar Ninguno, presionar Enter

Selecciona tu adaptador de implementación

por defecto: (Nitro)

Presiona la tecla Enter

¿Qué complementos te gustaría para tu proyecto?

Ninguno

Presiona Enter (TanStack Query se instalará manualmente)

¿Le gustaría algún ejemplo?

Ninguno

Presiona la tecla Enter

Después de completar la instalación, navegue a su directorio de proyecto.

4

TanStack Start usa Vite como la herramienta de compilar. Por defecto, Vite intenta agrupar las dependencias para el navegador. Sin embargo, el driver de Node.js depende de mongodb-client-encryption, un módulo nativo del lado del servidor que causa errores cuando Vite lo agrupa para entornos de navegador.

Para evitar esto, configura Vite para excluir el módulo mongodb-client-encryption de la optimización y el renderizado del lado del servidor.

Navegue a vite.config.ts en la raíz de su proyecto y reemplace el contenido con el siguiente código:

vite.config.ts
import { defineConfig } from 'vite'
import { devtools } from '@tanstack/devtools-vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import viteReact from '@vitejs/plugin-react'
import viteTsConfigPaths from 'vite-tsconfig-paths'
import tailwindcss from '@tailwindcss/vite'
import { nitro } from 'nitro/vite'
const config = defineConfig({
plugins: [
devtools(),
nitro(),
// this is the plugin that enables path aliases
viteTsConfigPaths({
projects: ['./tsconfig.json'],
}),
tailwindcss(),
tanstackStart(),
viteReact(),
],
optimizeDeps: {
// Exclude this server-side dependency to avoid bundling errors
exclude: ['mongodb-client-encryption'],
},
ssr: {
// Ensure this module is externalized during server-side rendering
external: ['mongodb-client-encryption'],
},
})
export default config
5

Instale el controlador Node.js para permitir que el código del servidor se conecte a la base de datos e instale TanStack Query para administrar la obtención de datos en el frontend.

Ejecuta el siguiente comando en el directorio raíz de tu proyecto:

npm install mongodb @tanstack/react-query
6

El asistente de instalación creó archivos que no necesitas. Para mantener el proyecto limpio y evitar confusiones con las autoimportaciones, borre los directorios data y demo.

Ejecuta los siguientes comandos en la raíz de tu proyecto:

rm -rf src/data
rm -rf src/routes/demo

Después de configurar la estructura del proyecto, sigue los pasos de esta sección para configurar el backend.

1

Crea un archivo .env en la raíz de tu proyecto para almacenar de forma segura tu URI de conexión.

Ejecuta el siguiente comando en el directorio raíz de tu proyecto:

touch .env

Abre el archivo .env y añade tu URI de conexión:

MONGODB_URI=<Your Connection URI>

Nota

Reemplaza <Your Connection URI> con el URI de conexión que has recibido de MongoDB Atlas.

2

Crea un archivo TypeScript dedicado para inicializar el cliente de MongoDB.

Ejecuta los siguientes comandos en la raíz de tu proyecto para crear la estructura de archivos:

mkdir -p src/lib
touch src/lib/db.ts

Abre src/lib/db.ts y pega el siguiente código:

src/lib/db.ts
import { MongoClient } from "mongodb"
// Connection string from the MongoDB atlas dashboard
const uri = process.env.MONGODB_URI
let connected = false
let client: MongoClient
export async function connectToDatabase() {
if (!uri) {
throw new Error("MONGODB_URI is not defined in environment variables")
}
if (!connected) {
try {
client = new MongoClient(uri)
await client.connect()
connected = true
} catch (error) {
throw new Error(`Failed to connect to database: ${error instanceof Error ? error.message : 'Unknown error'}`)
}
}
return client.db("sample_restaurants")
}

Este archivo contiene la función connectToDatabase() que se conecta a tu clúster de MongoDB y a la base de datos sample_restaurants. La base de datos sample_restaurants contiene datos de restaurantes de la ciudad de Nueva York, incluidos campos como el nombre del restaurante, el tipo de cocina, el distrito y la información de dirección.

3

TanStack Start utiliza funciones de servidor para ejecutar código de forma segura en el servidor. Crea un archivo dedicado para gestionar las consultas de la base de datos.

Ejecuta los siguientes comandos en la raíz de tu proyecto para crear un archivo restaurants.ts:

mkdir -p src/server
touch src/server/restaurants.ts

Abre src/server/restaurants.ts y pega el siguiente código:

src/servidor/restaurants.ts
import { createServerFn } from "@tanstack/react-start"
import { connectToDatabase } from "../lib/db"
export interface Restaurant {
_id: string
address: {
building: string
coord: [number, number]
street: string
zipcode: string
}
borough: string
cuisine: string
name: string
restaurant_id: string
}
// Gets a list of all restaurants from the database
export const getAllRestaurants = createServerFn({ method: 'GET'})
.handler(async () => {
const db = await connectToDatabase()
const restaurants = await db
.collection<Restaurant>("restaurants")
.find({})
.limit(100)
.toArray()
return restaurants.map((restaurant) => ({
...restaurant,
_id: restaurant._id.toString(),
}))
})
// Gets a list of restaurants in Queens with "Moon" in the name
export const getRestaurantsByBorough = createServerFn({ method: 'GET'})
.handler(async () => {
const db = await connectToDatabase()
const restaurants = await db
.collection<Restaurant>("restaurants")
.find({
borough: 'Queens',
name: {$regex: 'Moon', $options: 'i'} // case-insensitive match
})
.limit(100)
.toArray()
// Convert ObjectId to string for client-side serialization
return restaurants.map((restaurant) => ({
...restaurant,
_id: restaurant._id.toString(),
}))
})

Este archivo contiene dos funciones, getAllRestaurants() y getRestaurantsByBorough(). Estas dos funciones query tu clúster de MongoDB y devuelven los datos solicitados.

Después de establecer la base de datos y la capa de servidor, siga los pasos de esta sección para completar la gestión de datos y la capa de presentación.

1

Navega a src/components/Header.tsx y reemplaza el contenido con el siguiente código:

src/componentes/Header.tsx
import { Link } from "@tanstack/react-router"
export function Header() {
return(
<>
<nav className="bg-white px-6 py-2 shadow-md">
<div className="flex justify-between items-center gap-8">
<Link to ="/">
<img
alt="MongoDB logo"
className="h-10 inline"
src="https://d3cy9zhslanhfa.cloudfront.net/media/3800C044-6298-4575-A05D5C6B7623EE37/4B45D0EC-3482-4759-82DA37D8EA07D229/webimage-8A27671A-8A53-45DC-89D7BF8537F15A0D.png"
width="120"
height="40"
loading="eager"
style={{ maxHeight: '2.5rem', width: 'auto' }}
/>
</Link>
<Link to ="/browse" className="text-lime-800 text-lg font-semibold hover:text-green-700">
Browse
</Link>
</div>
</nav>
</>
)
}

Este componente muestra el encabezado sobre los resultados del restaurante e incluye el enlace de navegación y el logotipo. Estos permiten navegar entre rutas.

2

Ejecuta el siguiente comando desde la raíz del proyecto para crear el componente RestaurantList:

touch src/components/RestaurantList.tsx

Pega el siguiente código en src/components/RestaurantList.tsx:

src/components/RestaurantList.tsx
import {Restaurant} from "../server/restaurants"
type Props = {
restaurants: Restaurant[]
}
export function RestaurantList({restaurants}: Props) {
return (
<div className="overflow-hidden rounded-lg border border-gray-200 shadow-md">
<table className="w-full">
<thead className="bg-gray-50">
<tr>
<th className="px-4 py-3 text-left text-sm font-bold text-gray-700">Name</th>
<th className="px-4 py-3 text-left text-sm font-bold text-gray-700">Borough</th>
<th className="px-4 py-3 text-left text-sm font-bold text-gray-700">Cuisine</th>
</tr>
</thead>
<tbody className="divide-y divide-gray-200">
{restaurants.map((restaurant) => (
<tr key={restaurant._id}>
<td className="px-4 py-3">{restaurant.name}</td>
<td className="px-4 py-3">{restaurant.borough}</td>
<td className="px-4 py-3">{restaurant.cuisine}</td>
</tr>
))}
</tbody>
</table>
</div>
)
}

Este componente gestiona la visualización de los restaurantes. Los datos de la consulta se procesan como propiedades, las cuales se muestran en una tabla.

3

Navegue a src/routes/__root.tsx. Sustituye el contenido de __root.tsx por el siguiente código:

src/rutas/__root.tsx
import { HeadContent, Scripts, createRootRoute, Outlet } from '@tanstack/react-router'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import '../styles.css'
import {Header} from '../components/Header'
//Configure TanStack Query Client with cache and retry options
const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: 60 * 1000, // Data stays fresh for one minute
retry: 1, // Retry failed requests once
retryDelay: 1000 // Wait one second before retrying
},
},
})
export const Route = createRootRoute({
component: () => (
<html lang="en">
<head>
<HeadContent />
</head>
<body>
<QueryClientProvider client={queryClient}>
<Header />
<main>
<Outlet />
</main>
</QueryClientProvider>
<Scripts />
</body>
</html>
),
// Handle 404 errors for non-existent routes
notFoundComponent: () => {
return (
<div className="p-6">
<h1 className="text-2xl font-bold">404 - Page Not Found</h1>
<p>The page you're looking for doesn't exist.</p>
</div>
)
}
})

Este archivo es un contenedor para toda tu aplicación. El código utiliza un QueryClientProvider para garantizar que TanStack Query gestione el estado de los datos.

4

Navegue a src/routes/index.tsx. Sustituye el contenido de index.tsx por el siguiente código:

src/routes/índice.tsx
import { createFileRoute } from "@tanstack/react-router";
import {useSuspenseQuery} from '@tanstack/react-query'
import { RestaurantList } from "../components/RestaurantList";
import { getAllRestaurants } from "../server/restaurants";
export const Route = createFileRoute('/')({
component: Home,
pendingComponent: () => (
<div className="p-6 text-gray-500">
Loading restaurants...
</div>
),
errorComponent: ({error}) => (
<div className="p-6 text-red-600">
<h2 className="text-xl font-bold">Connection Error</h2>
<p>{error.message}</p>
<p className="text-sm mt-2">Please check your MongoDB connection string in your .env file</p>
</div>
),
})
function Home() {
const{data: restaurants} = useSuspenseQuery({
queryKey:['restaurants'],
queryFn: () => getAllRestaurants(),
})
return (
<div className="w-full p-6">
<h2 className="text-lg font-semibold p-4">All Restaurants</h2>
<RestaurantList restaurants={restaurants} />
</div>
)
}

Esta ruta muestra los resultados de getAllRestaurants() utilizando los componentes Header y RestaurantList.

5

Ejecute el siguiente comando desde la raíz de su proyecto para crear la ruta browse.tsx.

touch src/routes/browse.tsx

Pega el siguiente código en src/routes/browse.tsx:

src/routes/browse.tsx
import { createFileRoute } from '@tanstack/react-router'
import { useSuspenseQuery } from '@tanstack/react-query'
import { RestaurantList } from '../components/RestaurantList'
import { getRestaurantsByBorough } from '../server/restaurants'
export const Route = createFileRoute('/browse')({
component: BrowsePage,
// Display error UI if MongoDB connection or query fails
errorComponent: ({ error }) => (
<div className="p-6 text-red-600">
<h2 className="text-xl font-bold">Connection Error</h2>
<p>{error.message}</p>
<p className="text-sm mt-2">
Please check your MongoDB connection string in your .env file
</p>
</div>
),
})
function BrowsePage() {
// Fetch filtered restaurants using TanStack Query
// Query includes borough and search term in the key for proper caching
const { data: restaurants } = useSuspenseQuery({
queryKey: ['restaurants', 'queens', 'moon'], // Unique cache key for this filtered query
queryFn: () => getRestaurantsByBorough(), // Server function with MongoDB filter
})
return (
<div className='w-full p-6'>
<h2 className='text-lg font-semibold p-4'>
Queens Restaurants with "Moon" in the Name
</h2>
<RestaurantList restaurants={restaurants} />
</div>
)
}

Esta página muestra una query filtrada de la base de datos sample_restaurants. Muestra todos los restaurantes en Queens con Moon en su nombre. También utiliza los componentes Header y RestaurantList.

Nota

Puede haber advertencias con subrayado rojo en su IDE en las líneas createFileRoute hasta que ejecute el servidor. Esto es normal. TanStack Router genera las definiciones de tipo de TypeScript necesarias para sus rutas cuando ejecuta por primera vez la aplicación con npm run dev. Después de que el servidor se inicie, las advertencias desaparecerán.

6

Antes de continuar, asegúrate de que tu árbol de archivos coincida estrechamente con la estructura a continuación. Puedes ignorar de forma segura cualquier archivo de proyecto adicional.

your-app/
├─ node_modules/
├─ public/
├─ src/
│ ├─ components/
│ │ ├─ Header.tsx <-- Logo and browse link
│ │ ├─ RestaurantList.tsx <-- Table that displays results of DB query
│ ├─ routes/
│ │ ├─ __root.tsx <-- Application wrapper
│ │ ├─ browse.tsx <-- Browse page, holds results of getRestaurantsByBorough()
│ │ ├─ index.tsx <-- Home page, holds results of getAllRestaurants()
│ ├─ server/
│ │ ├─ restaurants.ts <--- Server functions
│ ├─ lib/
│ │ ├─ db.ts <--- Database connection
├─ .env <-- Connection URI

Siga los pasos restantes para iniciar el servidor y visualizar los datos renderizados del restaurante.

1

Ejecute el siguiente comando en la raíz de su proyecto para iniciar el servidor de desarrollo:

npm run dev

Si es exitoso, el comando muestra la siguiente información en la terminal:

VITE v7.2.4 ready in 939 ms
➜ Local: http://localhost:3000/
➜ Network: use --host to expose
➜ press h + enter to show help
2

Abre http://localhost:3000/ en el navegador. La página de aterrizaje inicial muestra todos los restaurantes en la base de datos sample_restaurants.

La aplicación de destino que muestra todos los restaurantes en la base de datos sample_restaurants
3

Haga clic en el Browse enlace en el encabezado para ver una lista filtrada de restaurantes en Queens con Moon en el nombre.

La página de exploración muestra restaurantes filtrados de la base de datos sample_restaurants.

¡Felicidades por completar el tutorial de inicio rápido!

Después de completar estos pasos, tendrás una aplicación TanStack Start que se conectará a tu implementación de MongoDB, ejecutará queries sobre datos de restaurantes de muestra y renderizará los resultados con una reactividad en tiempo real.

Para obtener más información sobre TanStack Start, el ecosistema de TanStack y MongoDB, consulta los siguientes recursos:

Volver

Integración de Nuxt y Vue

En esta página