TanStack Start Server Runtime and APIs

Use this skill when the task is primarily about TanStack Start's request lifecycle, server-side APIs, middleware flow, or safe server and client separation.

Scope

• server functions and server routes
• middleware composition and ordering
• src/server.ts and src/client.tsx entrypoint concerns
• request and response lifecycle
• environment functions and env-variable boundaries
• typed request context propagation

Routing cues

• createServerFn, useServerFn, server: { handlers }, createHandlers, createMiddleware, useSession, setResponseHeaders, setResponseStatus, src/server.ts, src/client.tsx, or VITE_ env boundaries -> use this skill
• SSR-mode selection, hydration, or import protection as the primary concern -> use tanstack-start-rendering-and-execution
• hosting provider selection, Nitro, Cloudflare, Netlify, or observability plumbing -> use tanstack-start-deployment-and-runtime-ops
• auth provider strategy, sessions as product behavior, or route protection flows -> use tanstack-start-auth-and-backend-integrations

Workflow

1. Read references/server-runtime-and-request-flow.md first.
2. Decide whether the task needs a server function, a server route, or middleware before writing code.
3. Keep server-only helpers in server-only files and import them from the server boundary, not from arbitrary shared UI modules.
4. Keep src/server.ts minimal unless the app truly needs custom fetch handling or typed request context at the entry point.

Quick example

import { createServerFn } from '@tanstack/react-start'

export const saveDraft = createServerFn({ method: 'POST' })
  .inputValidator((data: { title: string }) => data)
  .handler(async ({ data }) => {
    return db.drafts.insert(data)
  })

Guardrails

• Prefer static imports for server functions. The docs explicitly warn against dynamic imports for them.
• createServerFn() is a networked server boundary. createServerOnlyFn() and createClientOnlyFn() are runtime-enforced environment helpers, not RPCs.
• Request middleware and function middleware are not interchangeable. Function middleware can depend on request middleware, not the other way around.
• Middleware ordering matters. Dependency-first execution and missing next() calls change behavior quickly.
• Route-level middleware runs before handler-specific middleware in server routes.
• Server route paths must stay unique; mixed file-name and directory forms can collide.
• Client code only gets VITE_ values from import.meta.env. Secrets stay in process.env on the server.
• If the client needs a runtime-only secret-derived value, pass it through a loader or server function instead of reading non-VITE_ env vars directly.
• staticFunctionMiddleware is experimental and must be the final middleware on a static server function.

Canonical APIs

• createServerFn
• useServerFn
• createMiddleware
• createStartHandler
• createServerEntry
• setResponseHeaders
• setResponseStatus
• getRequest
• getRequestHeader

Maintenance

• Snapshot date: 2026-03-24
• Package snapshot: @tanstack/react-start@1.167.2 latest published 2026-03-21
• Docs status snapshot: official docs still label TanStack Start as RC / feature-complete and recommend pinning versions for production

References

• references/server-runtime-and-request-flow.md