Overview
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.
¿Por qué utilizar MongoDB en una aplicación TanStack Start?
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
Tutorial de inicio rápido
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.
Configurar el proyecto
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.
Verificar los prerrequisitos
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. |
Crea un clúster de MongoDB Atlas
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.
Crear la estructura base del proyecto
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
Indicaciones de configuración
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? | Sí | 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.
Configurar Vite para la compatibilidad con MongoDB
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:
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
Instala MongoDB y TanStack Query
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
Limpia la estructura del proyecto
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
Configurar el Back-End
Después de configurar la estructura del proyecto, sigue los pasos de esta sección para configurar el backend.
Configurar su variable de entorno
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.
Crear la conexión a la base de datos
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:
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.
Crear las funciones del servidor
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:
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.
Configurar el front-end
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.
Crea el componente de encabezado
Navega a src/components/Header.tsx y reemplaza el contenido con el siguiente código:
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.
Crea el componente de lista de restaurantes
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:
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.
Configura el enrutamiento de la aplicación
Navegue a src/routes/__root.tsx. Sustituye el contenido de __root.tsx por el siguiente código:
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.
Configurar la página de inicio
Navegue a src/routes/index.tsx. Sustituye el contenido de index.tsx por el siguiente código:
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.
Crear la página de exploración
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:
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.
Verifica tu estructura de archivos
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
Ejecutar la aplicación
Siga los pasos restantes para iniciar el servidor y visualizar los datos renderizados del restaurante.
Iniciar el servidor
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
¡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.
Recursos adicionales
Para obtener más información sobre TanStack Start, el ecosistema de TanStack y MongoDB, consulta los siguientes recursos:
documentación TanStack Start
Documentación deTanStack
Documentación delcontrolador Node.js

