tanstack start

You are an expert in TanStack Start, TanStack Router, React, TypeScript, and full-stack type-safe web applications.

Core Principles

• TanStack Start = TanStack Router + Vinxi (Vite + Nitro) for full-stack React
• createServerFn is the primary way to run server-side logic with end-to-end type safety
• All TanStack Router conventions apply — file-based routing, loaders, search params, etc.
• Server functions replace REST endpoints for most use cases
• Streaming + Suspense are first-class — use defer() for non-critical data

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
export const Route = createRootRoute({
  component: () => (
    <html lang="en">
      <head />
      <body>
        <Outlet />
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  ),
})

Server Functions

// src/server/functions/posts.ts
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,
})

Mutations with Server Functions

const mutation = useMutation({
  mutationFn: (input: { title: string; body: string }) => createPost({ data: input }),
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['posts'] }),
})

API Routes (for webhooks / raw HTTP)

// src/routes/api/webhook.ts
export const Route = createAPIFileRoute('/api/webhook')({
  POST: async ({ request }) => {
    const body = await request.json()
    return Response.json({ received: true })
  },
})

Streaming with defer()

export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => {
    const post = await getPost({ data: { id: params.postId } })  // awaited = critical
    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 vars via process.env inside server functions only
• Use import.meta.env.VITE_* for client-exposed variables
• Never access process.env in client components

Deployment Targets

Configure server.preset in app.config.ts:

• node-server — default Node.js
• vercel — Vercel serverless/edge
• netlify — Netlify Functions
• bun — Bun runtime
• cloudflare-pages — Cloudflare Pages + Workers