MongoDB.local SF, Jan 15: See the speaker lineup & ship your AI vision faster. Use WEB50 to save 50%
Find out more >
Menu Docs
Página inicial do Docs
/ /

Integrar o MongoDB com o início do TantoStack

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.

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

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

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 .

1

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.

2

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.

3

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

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 .

4

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:

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 o Driver Node.js para permitir que o código do servidor se conecte ao banco de dados e instale o Tanto que o Query for gerenciado a busca de dados no frontend.

Execute o seguinte comando na raiz do seu projeto :

npm install mongodb @tanstack/react-query
6

O assistente de instalação criou arquivos de que você não precisa. Para manter o projeto limpo e evitar confusão de importação automática, exclua os diretórios data e demo.

Execute os seguintes comandos na raiz do seu projeto :

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

Após configurar a estrutura do projeto , siga as etapas nesta seção para configurar o backend.

1

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.

2

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:

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

3

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:

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 arquivo contém duas funções, getAllRestaurants() e getRestaurantsByBorough(). Essas duas funções consultam seu cluster MongoDB e retornam os dados solicitados.

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.

1

Navegue até src/components/Header.tsx e substitua o conteúdo pelo seguinte código:

src/components/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 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.

2

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:

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.

3

Navegue até src/routes/__root.tsx. Substitua o conteúdo de __root.tsx pelo seguinte código:

src/routes/__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>
)
}
})

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.

4

Navegue até src/routes/index.tsx. Substitua o conteúdo de index.tsx pelo seguinte código:

src/routes/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 rota exibe os resultados do getAllRestaurants() utilizando os componentes Header e RestaurantList.

5

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:

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.

6

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

Siga as etapas restantes para iniciar o servidor e visualizar os dados do restaurante renderizados.

1

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
2

Abra http://localhost:3000/ no seu navegador. A página de destino inicial exibe todos os restaurantes no banco de dados do sample_restaurants.

A aplicação de destino que exibe todos os restaurantes no banco de dados sample_restaurants
3

Clique no link Browse no cabeçalho para ver uma lista filtrada de restaurantes no Queins com Moon no nome.

A página de navegação exibe restaurantes filtrados do banco de dados sample_restaurants .

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.

Para saber mais sobre o TantoStack Start, o ecossistemaTanStack e o MongoDB, consulte os seguintes recursos:

Voltar

Integração de meteor e Vue

Nesta página