Visão geral
Este guia demonstra como construir um aplicação web moderno com TantoStack Start e MongoDB. O TaStack Start é uma framework full-stack que integra o desenvolvimento de front-end e back-end usando o React e bibliotecas populares como o TaStack Router e a Query do Query do ecossistema TaStack.
O aplicativo neste tutorial consiste nas seguintes camadas:
Camada de banco de dados: o MongoDB armazena e recupera dados.
Camada do servidor: oTanStack Start fornece os endpoints e a lógica da API para conectar seu frontend ao banco de dados MongoDB .
Camada de gerenciamento de dados: oTanStack Query gerencia o estado do lado do servidor no frontend, unificando a lógica da busca de dados, dos estados de carregamento e do tratamento de erros.
Camada de apresentação: o React implementa a interface do usuário usando os dados da queryTanStack.
Por que usar o MongoDB em um aplicativo Iniciar do TantoStack?
O modelo de documento do MongoDB armazena dados como documentos semelhantes a JSON, facilitando o trabalho com objetos JavaScript sem mapeamento complexo. Isso se alinha aos componentes React do TantoStack Start e às interfaces TypeScript.
OTanStack Query lida com a camada de dados de forma eficiente, armazenando em cache respostas do MongoDB , gerenciando estados de carregamento e sincronizando dados entre componentes. Isso elimina o gerenciamento manual de estado e reduz as chamadas redundantes ao banco de dados .
Essa combinação funciona bem para aplicativos que precisam das seguintes funcionalidades:
Estruturas de dados flexíveis que podem desenvolver-se ao longo do tempo
Atualizações de dados em tempo real com código mínimo do lado do cliente
Digite segurança do banco de dados para a interface do usuário
Cache eficiente e sincronização de dados em segundo plano
Tutorial de início rápido
Este tutorial ajuda você a criar um aplicação Start que se integra ao MongoDB. O aplicação acessa dados de restaurante de amostra e exibe os resultados em um site hospedado localmente. Ele inclui instruções sobre como conectar seu cluster MongoDB hospedado no MongoDB Atlas e acessar e exibir informações de seu banco de dados.
Dica
Se você preferir se conectar ao MongoDB usando o driver Node.js sem oTanStack Start, consulte o guia Introduçãoao driver Node.js
Configurar seu projeto
Siga as etapas nesta seção para instalar dependências do projeto , criar um cluster do Atlas e configurar os diretórios do aplicação .
Verifique os pré-requisitos
Para criar o aplicação Quick Start, verifique se você tem o seguinte software instalado:
Pré-requisitos | Notas |
|---|---|
Use a versão 20 ou posterior. | |
Editor de Código | Este tutorial utiliza Visual Studio Code, mas você pode utilizar o editor de sua escolha. |
Terminal | Para usuários do MacOS, use o Terminal ou um aplicativo semelhante. Para usuários do Windows, use o PowerShell. |
Criar um cluster MongoDB Atlas
O MongoDB Atlas é um serviço de banco de dados de nuvem totalmente gerenciado que hospeda suas implementações do MongoDB . Se você não tiver uma implementação do MongoDB , crie um cluster gratuito (nenhum cartão de crédito necessário) concluindo o tutorial de Introdução ao MongoDB . O tutorial de Introdução ao MongoDB também demonstra como carregar bancos de dados de exemplo em seu cluster, incluindo o sample_restaurants banco de dados usado neste tutorial.
Para se conectar ao cluster, você deve usar um URI de conexão. Para recuperar seu URI de conexão, siga as instruções no tutorial Conectar ao Seu Cluster na documentação do Atlas .
Dica
Salve seu URI de conexão em um local seguro.
Criar o esqueleto do projeto
Use a CLI oficial do Iniciar do Sol para inicializar a estrutura do projeto . Abra o terminal e navegue até o diretório de projeto desejado.
Execute o comando de inicialização:
npm create @tanstack/start@latest
Solicitações de configuração
O assistente de instalação orienta você na configuração. Selecione as seguintes opções:
Prompt | Entrada | em ação |
|---|---|---|
Que nome você gostaria de dar ao seu projeto? | O nome do projeto desejado | Digite o nome e pressione Enter |
Você gostaria de usar o Tailwind CSS? | Sim | Digite Y, pressione Enter |
Selecione uma cadeia de ferramentas | Padrão (nenhum) | Selecione Nenhum e pressione Enter |
Selecione seu adaptador de sistema | Padrão: (Nitro) | Pressione Enter |
Quais add-ons você gostaria para o seu projeto? | none | Pressione Enter (a consulta doTanStack será instalada manualmente) |
Você gostaria de alguns exemplos? | none | Pressione Enter |
Após a conclusão da instalação, navegue até o diretório do projeto .
Configurar o Vite para compatibilidade com o MongoDB
O TantoStack Start usa o Vite como ferramenta de construção. Por padrão, o Vite tenta agrupar dependências para o navegador. No entanto, o driver do Node.js depende do mongodb-client-encryption, um módulo nativo do lado do servidor que causa erros quando o Vite o agrupa para ambientes de navegador.
Para evitar isso, configure o Vite para excluir o módulo mongodb-client-encryption da otimização e da renderização no lado do servidor.
Navegue até vite.config.ts na raiz do seu projeto e substitua o conteúdo pelo seguinte 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
Configurar o back-end
Após configurar a estrutura do projeto , siga as etapas nesta seção para configurar o backend.
Configure sua variável de ambiente
Crie um arquivo .env na raiz do seu projeto para armazenar com segurança seu URI de conexão.
Execute o seguinte comando na raiz do seu projeto :
touch .env
Abra o arquivo .env e adicione seu URI de conexão:
MONGODB_URI=<Your Connection URI>
Observação
Substitua <Your Connection URI> pelo URI de conexão que você recebeu do MongoDB Atlas.
Criar a conexão do banco de dados
Crie um arquivo TypeScript dedicado para inicializar o cliente MongoDB .
Execute os seguintes comandos na raiz do seu projeto para criar a estrutura do arquivo:
mkdir -p src/lib touch src/lib/db.ts
Abra o src/lib/db.ts e cole o seguinte 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 arquivo contém a função connectToDatabase() que se conecta ao seu cluster MongoDB e ao banco de dados sample_restaurants. O banco de dados sample_restaurants contém dados de restaurantes da cidade de Nova York, incluindo campos como nome do restaurante, tipo de cozinha, bairro e informações de endereço.
Criar as funções do servidor
O TantoStack Start usa funções de servidor para executar código com segurança no servidor. Crie um arquivo dedicado para lidar com as queries do banco de dados .
Execute os seguintes comandos na raiz do seu projeto para criar um arquivo restaurants.ts:
mkdir -p src/server touch src/server/restaurants.ts
Abra o src/server/restaurants.ts e cole o seguinte 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 arquivo contém duas funções, getAllRestaurants() e getRestaurantsByBorough(). Essas duas funções consultam seu cluster MongoDB e retornam os dados solicitados.
Configurar o front-end
Após configurar a camada de banco de dados e servidor , siga as etapas nesta seção para concluir a camada de apresentação e gerenciamento de dados.
Criar o componente de cabeçalho
Navegue até src/components/Header.tsx e substitua o conteúdo pelo seguinte 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 renderiza o cabeçalho acima dos resultados do restaurante e contém o link de navegação e o logotipo. Eles permitem que você navegue entre as rotas.
Criar o componente da lista de restaurantes
Execute o seguinte comando a partir da raiz do seu projeto para criar o componente RestaurantList:
touch src/components/RestaurantList.tsx
Cole o seguinte código em 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 lida com a exibição dos restaurantes. Os dados da query são tratados como props, e os props são exibidos dentro de uma tabela.
Configurar roteamento de aplicação
Navegue até src/routes/__root.tsx. Substitua o conteúdo de __root.tsx pelo seguinte 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> ) } })
Esse arquivo é um wrapper em torno de todo o aplicação. O código usa um QueryClientProvider para garantir que a query doTanStack gerencie o estado dos dados.
Configurar a página inicial
Navegue até src/routes/index.tsx. Substitua o conteúdo de index.tsx pelo seguinte 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 rota exibe os resultados do getAllRestaurants() utilizando os componentes Header e RestaurantList.
Criar a página de navegação
Execute o seguinte comando a partir da raiz do seu projeto para criar a rota browse.tsx.
touch src/routes/browse.tsx
Cole o seguinte código em 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 exibe uma query filtrada do banco de dados do sample_restaurants. Ela exibe todos os restaurantes no Queins com Moon em seu nome. Ele também usa os componentes Header e RestaurantList.
Observação
Você pode ter avisos de sublinhado vermelho em seu IDE nas linhas createFileRoute até executar o servidor. Isso é normal. O Roteador bandeja gera as definições de tipo TypeScript necessárias para suas rotas quando você executa pela primeira vez o aplicação com npm run dev. Após o início do servidor , os avisos desaparecerão.
Verifique a estrutura do seu arquivo
Antes de continuar, verifique se sua árvore de arquivos corresponde corretamente à estrutura abaixo. Você pode ignorar com segurança quaisquer arquivos de projeto adicionais.
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
Execute seu aplicativo
Siga as etapas restantes para iniciar o servidor e visualizar os dados do restaurante renderizados.
Iniciar o servidor
Execute o seguinte comando na raiz do seu projeto para iniciar o servidor de desenvolvimento:
npm run dev
Se bem-sucedido, o comando gera as seguintes informações no terminal:
VITE v7.2.4 ready in 939 ms ➜ Local: http://localhost:3000/ ➜ Network: use --host to expose ➜ press h + enter to show help
Parabéns por concluir o tutorial de início rápido!
Depois de concluir estas etapas, você terá um aplicação DataStack Start que se conecta à implementação do MongoDB , executa queries em dados de restaurantes de exemplo e renderiza os resultados com reatividade em tempo real.
Recursos adicionais
Para saber mais sobre o TantoStack Start, o ecossistemaTanStack e o MongoDB, consulte os seguintes recursos:
Documentação do iníciodoTanStack
DocumentaçãodoTanStack

