跳到主要内容
非官方简体中文翻译，内容版权归 Mastra 所有，遵循 Apache-2.0 许可。

TanStack Start

Build a tool-calling Mastra agent in TanStack Start, then mount the Mastra server on a catch-all API route. The Server Adapters overview explains the shared concepts, and the TanStack Start adapter reference documents the package API.

Before you begin
Before you begin的直接链接

  • You'll need an API key from a supported model provider. If you don't have a preference, use OpenAI.
  • Install Node.js v22.13.0 or later

Create a new TanStack Start app (optional)
Create a new TanStack Start app (optional)的直接链接

You need a running TanStack Start app with a src/routes directory. If you don't already have one, follow the TanStack Start quick start to create and run an app before continuing.

Initialize Mastra
Initialize Mastra的直接链接

From your TanStack Start project directory, run mastra init. When prompted, choose a provider, such as OpenAI, and enter your API key:

npx mastra@latest init

This creates a src/mastra directory with an example weather agent and the following files:

  • index.ts: Mastra configuration, including memory
  • tools/weather-tool.ts: A tool that fetches weather for a location
  • agents/weather-agent.ts: A weather agent with instructions to use the tool

You'll pass the Mastra instance exported from src/mastra/index.ts to the server adapter.

Configure Vite and Nitro
Configure Vite and Nitro的直接链接

Update vite.config.ts so Vite and Nitro leave DuckDB's and @mastra/core's Node-only dependencies out of their processing pipelines:

vite.config.ts
 const config = defineConfig({
   resolve: { tsconfigPaths: true },
+  optimizeDeps: {
+    exclude: ['@mastra/duckdb', 'execa'],
+  },
   plugins: [
     devtools(),
-    nitro({ rollupConfig: { external: [/^@sentry\//] } }),
+    nitro({
+      rollupConfig: {
+        external: [/^@sentry\//, /^@duckdb\//],
+      },
+    }),

The optimizeDeps.exclude setting prevents Vite's development optimizer from opening DuckDB's native .node binary as JavaScript. Excluding execa stops the optimizer from pre-bundling the server-only dependency @mastra/core uses for local process execution; its transitive npm-run-path and unicorn-magic packages use Node-only conditional exports that the optimizer cannot resolve in the browser build. Adding /^@duckdb\// to Nitro's rollupConfig.external keeps DuckDB's native Node packages out of the production bundle so Node.js can load them at runtime.

These changes apply only to vite.config.ts; you don't need to change your application or Mastra source files.

Add the server adapter
Add the server adapter的直接链接

Install the TanStack Start server adapter and its Hono peer dependency:

npm install @mastra/tanstack-start@latest hono

Create a splat route that passes all supported HTTP methods to the adapter:

src/routes/api/$.ts
import { createStartRouteHandler } from '@mastra/tanstack-start'
import { createFileRoute } from '@tanstack/react-router'
import { mastra } from '../../mastra'

export const Route = createFileRoute('/api/$')({
  server: {
    handlers: createStartRouteHandler({ mastra }),
  },
})

The prefix option defaults to /api and must match the splat route's mount path. For example, when mounting the adapter at src/routes/api/mastra/$.ts, use createStartRouteHandler({ mastra, prefix: '/api/mastra' }).

The adapter exposes Mastra's REST and streaming endpoints, custom API routes, MCP endpoints, and A2A endpoints. A2A tasks use an in-memory task store.

Test your agent
Test your agent的直接链接

Start your TanStack Start app:

npm run dev

In a separate terminal window, use curl to ask the weather agent:

curl -X POST http://localhost:3000/api/agents/weather-agent/generate -H "Content-Type: application/json" -d "{\"messages\":[{\"role\":\"user\",\"content\":\"What is the weather like in Seoul?\"}]}"

The endpoint returns a complete JSON response from the agent.

Next steps
Next steps的直接链接

Extend the project with your own agents and application logic:

On this page