Skip to main content

TanStack Start adapter

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

Installation
Direct link to Installation

Install the TanStack Start adapter and its Hono peer dependency:

npm install @mastra/tanstack-start@latest hono

Usage example
Direct link to 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
Direct link to Signature

function createStartRouteHandler(options: StartRouteHandlerOptions): StartRouteHandlers

Parameters
Direct link to 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
Direct link to 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
Direct link to 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
Direct link to 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
Direct link to 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