oakoss 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-formskill is available, delegate form state management, validation, and field patterns to it. If thelocal-firstskill is available, delegate local-first architecture decisions and sync engine selection to it. If theelectricsqlskill is available, delegate ElectricSQL shapes, auth configuration, and write patterns to it. If thetanstack-dbskill 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