TanStack Start
Full-stack React framework built on TanStack Router. Type-safe server functions via RPC, SSR/streaming, middleware composition, and deployment to Cloudflare Workers, Vercel, Netlify, AWS Lambda, and more.
RC: TanStack Start is currently in Release Candidate status. APIs may still change before the stable 1.0 release.
Package: @tanstack/react-start
Quick Reference
| Pattern | Usage |
|---|
createServerFn() | GET (default) — idempotent, cacheable data fetching |
createServerFn({method: 'POST'}) | Mutations that change data |
.inputValidator(zodSchema) | Input validation before handler |
.handler(async ({data}) => {}) | Server-side logic with typed input data |
getRequest() | Access full incoming Request inside handler/middleware |
getRequestHeader(name) | Read a single request header by name |
setResponseHeaders(headers) | Set outgoing response headers (caching, cookies) |
useServerFn(fn) | Wrap server function for component use with pending state |
createMiddleware().server(fn) | Request middleware for cross-cutting concerns |
.middleware([dep]) | Compose middleware with dependencies |
next({context: {}}) | Pass data downstream through middleware chain |
createMiddleware({type: 'function'}) | Function-level middleware with input validation |
requestMiddleware in createStart() | Global middleware for all requests (SSR, fns, routes) |
functionMiddleware in createStart() | Global middleware for server functions only |
createIsomorphicFn() | Different implementations per environment |
createServerOnlyFn() | Server-only utility — crashes if called from client |
createClientOnlyFn() | Client-only utility — crashes if called from server |
useSession() | Cookie-based session with encryption and secure settings |
session.update() | Update session data |
session.clear() | Clear session (logout) |
beforeLoad | Auth check before route loads |
_authenticated.tsx | Pathless layout route for grouped protection |
throw redirect({to: '/login'}) | Redirect with return URL |
await ensureQueryData() | Block SSR on critical data |
prefetchQuery() | Start fetch, don't block SSR |
<Suspense> boundaries | Define streaming chunks |
head: ({loaderData}) => ({}) | Meta tags, Open Graph, favicons |
head.scripts + JSON-LD | Structured data for LLMO (schema.org) |
llms.txt server route | AI system guidance file |
headers: () => ({...}) | ISR / cache-control on route definition |
server: {handlers: {GET, POST}} | API routes on createFileRoute |
ssr: false | Disable SSR for specific routes (SPA mode) |
Execution Boundaries
| Function | Runs On | Client Can Call? | Use For |
|---|
createServerFn() | Server | Yes (RPC stub) | Data fetching, mutations |
createServerOnlyFn() | Server | No (throws) | Secrets, DB connections |
createClientOnlyFn() | Client | N/A | localStorage, DOM APIs |
createIsomorphicFn() | Both | N/A | Per-environment implementations |
Deployment (Vite Plugins)
| Platform | Plugin | Runtime |
|---|
| Cloudflare | @cloudflare/vite-plugin | Workers |
| Netlify | @netlify/vite-plugin-tanstack-start | Node |
| Vercel | nitro/vite (preset: 'vercel') | Node |
| Node.js/Docker | nitro/vite (preset: 'node-server') | Node |
| AWS Lambda | nitro/vite (preset: 'aws-lambda') | Node |
| Bun | nitro/vite (preset: 'bun') | Bun |
| Static | nitro/vite (preset: 'static') | None |
Common Mistakes
| Mistake | Fix |
|---|
No .inputValidator() on server functions | Always validate with Zod schemas |
Raw fetch instead of createServerFn | Loses type safety, serialization, and code splitting |
| Mixing server/client code without boundaries | Use createServerOnlyFn / createClientOnlyFn |
| Checking auth in every handler | Use middleware composition or beforeLoad |
| Awaiting all data in loader | Only await critical data, prefetch the rest |
Date.now() in render | Pass timestamp from loader (hydration mismatch) |
Missing nodejs_compat flag | Required in wrangler.toml for Cloudflare |
| GET for mutations | Use POST for create/update/delete |
| Cookies not forwarded to external APIs | Use getRequestHeader() or createIsomorphicFn |
process.env in loader (runs on both) | Wrap in createServerFn — loaders run client-side too |
| Unvalidated server env vars | Validate with Zod in .server.ts files |
| Storing auth tokens in localStorage | Use HTTP-only cookies via useSession |
| Exposing raw DB errors to client | Catch and return user-friendly messages, log details |
| No structured data for content pages | Add JSON-LD via head.scripts for AI discoverability |
Delegation
Use this skill for TanStack Start server functions, middleware, SSR/streaming, route protection, API routes, and deployment configuration. Delegate to tanstack-router for file-based routing, search params, and data loading patterns. Delegate to tanstack-query for cache management, optimistic updates, and query patterns.
If the tanstack-form skill is available, delegate form state management, validation, and field patterns to it. If the local-first skill is available, delegate local-first architecture decisions and sync engine selection to it. If the electricsql skill is available, delegate ElectricSQL shapes, auth configuration, and write patterns to it. If the tanstack-db skill is available, delegate reactive collections, live queries, and optimistic mutation patterns to it.
References
- Server Functions — createServerFn, useServerFn, validation, auth, request context, response headers, file uploads, streaming, TanStack Query integration
- Middleware — composition, function-level middleware, route-level middleware, global middleware, logging, rate limiting
- SSR and Streaming — Suspense, prerendering, ISR, cache-control, hybrid strategies, hydration safety
- Route Protection — beforeLoad, pathless layouts, session security, login/logout, header forwarding, Better Auth
- API Routes — server handlers, REST patterns, route-level middleware, webhooks, health check, server functions vs server routes
- Deployment — Vite plugins, adapter comparison, Cloudflare D1/KV/R2 bindings, Docker, prerendering
- SEO and Head Management — head property, meta tags, Open Graph, Twitter Cards, favicons, SEO helper
- LLM Optimization (LLMO) — JSON-LD structured data, schema.org, llms.txt, machine-readable endpoints, AI citation patterns
- Error Handling — discriminated unions, custom error classes, status codes, result types vs try-catch
- File Organization — entry points, plugin config, execution boundaries, env validation,.server.ts convention
- Known Issues — 10 documented issues with workarounds
- Query Integration — Router+Query setup, SSR integration, setupRouterSsrQueryIntegration, DevTools
- Integration Flows — form submission with cache update, infinite scroll, paginated tables, auth-protected routes, error handling
- Local-First Integration — shape proxy server functions, mixing server-based and local-first data, ElectricSQL deployment
- Electric Middleware — auth middleware for shape proxies, global middleware config, sendContext, function-level validation
