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

TanStack Start adapter

The @mastra/tanstack-start package mounts Mastra in a TanStack Start application. See Server Adapters for general adapter concepts.

Installation
Installation的直接链接

Install the TanStack Start adapter and its Hono peer dependency:

npm install @mastra/tanstack-start@latest hono

Usage example
Usage example的直接链接

Mount the adapter in a catch-all splat route:

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 at src/routes/api/mastra/$.ts, use createStartRouteHandler({ mastra, prefix: '/api/mastra' }).

Signature
Signature的直接链接

function createStartRouteHandler(options: StartRouteHandlerOptions): StartRouteHandlers

Parameters
Parameters的直接链接

mastra:

Mastra
Mastra instance whose server configuration and registered resources are exposed

tools?:

ToolsInput
= {}
Additional tools to register with the server

prefix?:

string
= '/api'
API route prefix, which must match the splat route mount path

Return value
Return value的直接链接

Returns a StartRouteHandlers object with GET, POST, PUT, DELETE, PATCH, OPTIONS, and HEAD properties. Each property is a handler with this signature:

(context: StartHandlerContext) => Response | Promise<Response>

The context type contains the incoming request and the splat route parameters:

type StartHandlerContext = {
  request: Request
  params: Record<string, string>
}

Serverless deployments & lazy initialization
Serverless deployments & lazy initialization的直接链接

The adapter exports its route handlers synchronously, then creates the underlying Hono app and MastraServer when the first request arrives. That initialized app is reused for subsequent requests in the same process, which supports serverless runtimes without top-level asynchronous initialization.

It uses the same Hono-based MastraServer core as the Next.js adapter. A2A endpoints use an in-memory task store, so task state lasts only for the lifetime of the process and isn't shared between serverless instances.

Body size limit
Body size limit的直接链接

Request bodies have a default limit of 4.5 MB. Requests that exceed the limit receive { error: 'Request body too large' }.

Set server.bodySizeLimit on the Mastra instance to configure the limit.

Middleware
Middleware的直接链接

Middleware configured with server.middleware or setServerMiddleware() runs through the adapter's Hono-based server, except on framework-public routes such as those marked requiresAuth: false. See Server middleware.

On this page