mindrally TanStack Start
TanStack Start is a full-stack React framework that layers server functions, SSR, streaming, and API routes on top of TanStack Router and a Vite/Nitro build pipeline, giving end-to-end type safety from server to client.
Workflow for Building a TanStack Start Feature
- Configure the app — Set up
app.config.tswith the Vite plugins and aserver.presetmatching the deployment target. - Define the root route — Create
src/routes/__root.tsxwith the HTML document shell (<html>,<head>,<body>,<Outlet>,<ScrollRestoration>,<Scripts>). - Write server functions — Use
createServerFn()with a.validator()and.handler()for any logic that must run on the server (database access, secrets, file I/O). - Wire server functions into routes — Call server functions from route
loaders for reads and from mutation hooks (useMutation) for writes. - Add API routes for raw HTTP — Use
createAPIFileRoutefor webhooks, OAuth callbacks, or endpoints that external services call directly. - Stream non-critical data — Wrap slow, non-blocking loader data in
defer()and render it with<Suspense>+<Await>. - Deploy — Pick the
server.presetfor the target platform and verify environment variable access rules before shipping.
Core Principles
- TanStack Start = TanStack Router + Vite + Nitro, giving full-stack React with a single type-safe codebase.
createServerFnis the primary mechanism for server-side logic — prefer it over hand-rolled REST endpoints for internal data access.- All TanStack Router conventions apply on top of Start: file-based routing, loaders, search param validation, and router context.
- Streaming and Suspense are first-class citizens; use
defer()for anything that shouldn't block the initial response. - Keep server-only code (secrets, DB clients, filesystem access) strictly inside server functions or API routes — never import it into client components.
Configuration
app.config.ts
import { defineConfig } from '@tanstack/start/config'
import tsConfigPaths from 'vite-tsconfig-paths'
export default defineConfig({
vite: { plugins: [tsConfigPaths()] },
server: {
preset: 'node-server', // or: 'vercel', 'netlify', 'bun', 'cloudflare-pages'
},
})
Root Route HTML Shell
// src/routes/__root.tsx
import { createRootRoute, Outlet, ScrollRestoration } from '@tanstack/react-router'
import { Scripts } from '@tanstack/start'
export const Route = createRootRoute({
component: () => (
<html lang="en">
<head />
<body>
<Outlet />
<ScrollRestoration />
<Scripts />
</body>
</html>
),
})
Server Functions
- Define server functions in a dedicated
src/server/functions/(or colocated*.server.ts) module for discoverability. - Always validate input with
.validator()(Zod is the common choice) before the handler runs — never trust client-supplieddata. - Throw descriptive
Errors (or a typed error) from handlers; TanStack Start serializes thrown errors back to the client. - Server functions can be called directly from loaders, actions, event handlers, or
useMutation— they behave like normal async functions on the client but execute on the server.
// src/server/functions/posts.ts
import { createServerFn } from '@tanstack/start'
import { z } from 'zod'
import { db } from '~/server/db'
export const getPost = createServerFn()
.validator(z.object({ id: z.string() }))
.handler(async ({ data }) => {
const post = await db.post.findUnique({ where: { id: data.id } })
if (!post) throw new Error('Post not found')
return post
})
export const createPost = createServerFn()
.validator(z.object({ title: z.string().min(1), body: z.string() }))
.handler(async ({ data }) => db.post.create({ data }))
Using Server Functions in Routes
export const Route = createFileRoute('/posts/$postId')({
loader: ({ params }) => getPost({ data: { id: params.postId } }),
component: PostDetail,
})
function PostDetail() {
const post = Route.useLoaderData()
return <h1>{post.title}</h1>
}
Mutations with Server Functions
import { useMutation } from '@tanstack/react-query'
import { useQueryClient } from '@tanstack/react-query'
import { createPost } from '~/server/functions/posts'
function NewPostForm() {
const queryClient = useQueryClient()
const mutation = useMutation({
mutationFn: (input: { title: string; body: string }) => createPost({ data: input }),
onSuccess: () => queryClient.invalidateQueries({ queryKey: ['posts'] }),
})
return (
<form
=> {
e.preventDefault()
const form = new FormData(e.currentTarget)
mutation.mutate({
title: String(form.get('title')),
body: String(form.get('body')),
})
}}
>
<input name="title" placeholder="Title" required />
<textarea name="body" placeholder="Body" required />
<button type="submit" disabled={mutation.isPending}>Publish</button>
</form>
)
}
API Routes
Use API routes for endpoints that must speak raw HTTP (webhooks, OAuth callbacks, health checks) instead of server functions, which are meant to be called from your own client code.
// src/routes/api/webhook.ts
import { createAPIFileRoute } from '@tanstack/start/api'
export const Route = createAPIFileRoute('/api/webhook')({
POST: async ({ request }) => {
const body = await request.json()
// verify signature, enqueue processing, etc.
return Response.json({ received: true })
},
})
Streaming with defer()
- Await only the data required for the initial paint; wrap everything else in
defer()so the shell renders immediately. - Pair deferred values with
<Suspense>and<Await>so the UI shows a fallback until the promise resolves.
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params }) => {
const post = await getPost({ data: { id: params.postId } }) // critical, awaited
const comments = getComments({ data: { postId: params.postId } }) // not awaited
return { post, comments: defer(comments) }
},
component: PostDetail,
})
function PostDetail() {
const { post, comments } = Route.useLoaderData()
return (
<div>
<h1>{post.title}</h1>
<Suspense fallback={<CommentsSkeleton />}>
<Await promise={comments}>{(c) => <CommentsList comments={c} />}</Await>
</Suspense>
</div>
)
}
Environment Variables
- Access server-only secrets via
process.envonly inside server functions or API routes. - Use
import.meta.env.VITE_*for any variable that must be exposed to the client bundle. - Never reference
process.envdirectly in a client component — Vite will not inline server secrets, and doing so is a common source of leaked configuration.
Deployment Targets
Configure server.preset in app.config.ts to match the hosting platform:
node-server— default, runs anywhere Node.js runs.vercel— Vercel serverless/edge functions.netlify— Netlify Functions.bun— Bun runtime.cloudflare-pages— Cloudflare Pages + Workers (watch for Node API compatibility gaps in server functions).
Common Mistakes
- Calling a server function's handler logic directly from a client component instead of going through
createServerFn— this breaks the client/server boundary and type inference. - Awaiting everything in a loader, which defeats the purpose of streaming and slows the initial response.
- Forgetting
.validator(), leaving handlers to trust unvalidated client input. - Mixing
process.envreads into shared utility modules that are imported by both client and server code.