Docs Menu
Docs Home
/ /

Integrar 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 de 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 mediante el uso de datos de consulta de TanStack.

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 características:

  • Estructuras de datos flexibles que pueden evolucionar con el tiempo

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

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

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

Este tutorial le guía en la creación de una aplicación TanStack Start que se integra con MongoDB. La aplicación accede a datos de muestra de restaurantes y muestra los resultados en un sitio web alojado localmente. Incluye instrucciones para conectar su clúster MongoDB alojado en MongoDB Atlas y acceder y mostrar información de su base de datos.

Tip

Si prefiere conectarse a MongoDB utilizando el controlador Node.js sin TanStack Start, consulte 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úrese de tener instalado el siguiente software:

Requisito previo
notas

Utilice la versión 20 o posterior.

Editor de código

Este tutorial utiliza Visual Studio Code, pero puedes usar el editor que prefieras.

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 utiliza 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

Guarde su 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 le guiará durante la configuración. Seleccione las siguientes opciones:

Prompt
Entrada
Acción

¿Qué nombre te gustaría ponerle a tu proyecto?

El nombre del proyecto que desees

Escriba el nombre y presione Enter

¿Te gustaría utilizar Tailwind CSS?

Escriba Y, presione Enter

Seleccione una cadena de herramientas

Predeterminado (Ninguno)

Seleccionar Ninguno, presionar Enter

Seleccione su adaptador de implementación

Predeterminado: (Nitro)

Presiona la tecla Enter

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

Ninguno

Presione Enter (TanStack Query se instalará manualmente)

¿Te gustaría algún ejemplo?

Ninguno

Presiona la tecla Enter

Una vez completada la instalación, navegue hasta el directorio de su proyecto.

4

TanStack Start usa Vite como herramienta de compilación. De forma predeterminada, Vite intenta agrupar las dependencias para el navegador. Sin embargo, el controlador de Node.js se basa en mongodb-client-encryption, un módulo nativo del servidor que causa errores cuando Vite lo agrupa para entornos de navegador.

Para evitar esto, configure Vite para excluir el módulo mongodb-client-encryption de la optimización y la representación 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.

Ejecute el siguiente comando en la raíz de su proyecto:

npm install mongodb @tanstack/react-query
6

El asistente de instalación creó archivos innecesarios. Para mantener el proyecto limpio y evitar confusiones con la importación automática, elimine los directorios data y demo.

Ejecute los siguientes comandos en la raíz de su proyecto:

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

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

1

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

Ejecute el siguiente comando en la raíz de su proyecto:

touch .env

Abra el archivo .env y agregue su URI de conexión:

MONGODB_URI=<Your Connection URI>

Nota

Reemplace <Your Connection URI> con la URI de conexión que recibió de MongoDB Atlas.

2

Cree un archivo TypeScript dedicado para inicializar el cliente MongoDB.

Ejecute los siguientes comandos en la raíz de su proyecto para crear la estructura de archivos:

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

Abra src/lib/db.ts y pegue 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 su 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, incluyendo campos como el nombre del restaurante, el tipo de cocina, el distrito y la 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 a 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

Abra src/server/restaurants.ts y pegue el siguiente código:

src/servidor/restaurantes.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 consultan el clúster de MongoDB y devuelven los datos solicitados.

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

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

Ejecute el siguiente comando desde la raíz de su proyecto para crear el componente RestaurantList:

touch src/components/RestaurantList.tsx

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

src/componentes/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

Vaya a src/routes/__root.tsx. Reemplace el contenido de __root.tsx con 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 encapsula toda la aplicación. El código usa un QueryClientProvider para garantizar que TanStack Query gestione el estado de los datos.

4

Vaya a src/routes/index.tsx. Reemplace el contenido de index.tsx con el siguiente código:

src/rutas/index.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

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

src/rutas/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 consulta filtrada de la base de datos sample_restaurants. Muestra todos los restaurantes de Queens con Moon en su nombre. También utiliza los componentes Header y RestaurantList.

Nota

Es posible que aparezcan advertencias subrayadas en rojo en su IDE en las líneas createFileRoute hasta que ejecute el servidor. Esto es normal. TanStack Router genera las definiciones de tipo TypeScript necesarias para sus rutas la primera vez que ejecuta la aplicación con npm run dev. Tras el inicio del servidor, las advertencias desaparecerán.

6

Antes de continuar, asegúrese de que su árbol de archivos coincida con la estructura a continuación. Puede ignorar 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 ver los datos del restaurante procesados.

1

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

npm run dev

Si tiene éxito, 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

Abra http://localhost:3000/ en su navegador. La página de inicio muestra todos los restaurantes de 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.

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

Después de completar estos pasos, tendrá una aplicación TanStack Start que se conecta a su implementación de MongoDB, ejecuta consultas en datos de restaurantes de muestra y presenta los resultados con reactividad en tiempo real.

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

Volver

Integración de Nuxt y Vue

En esta página