TanStack Start

Version: @tanstack/react-start@1.x Requires: React 18.0+, TypeScript 5.0+, Vite, TanStack Router

Quick Setup

npm install @tanstack/react-start @tanstack/react-router
npm install -D @tanstack/router-plugin

Vite Config

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'

export default defineConfig({
  plugins: [tanstackStart(), react()],
})

Root Route

// src/routes/__root.tsx
import {
  HeadContent,
  Outlet,
  Scripts,
  createRootRoute,
} from '@tanstack/react-router'

export const Route = createRootRoute({
  head: () => ({
    meta: [
      { charSet: 'utf-8' },
      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
    ],
  }),
  component: RootComponent,
})

function RootComponent() {
  return (
    <html lang="en">
      <head>
        <HeadContent />
      </head>
      <body>
        <Outlet />
        <Scripts />
      </body>
    </html>
  )
}

Devtools

Standalone (TanStack Router only):

npm install -D @tanstack/react-router-devtools

import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'

// In root layout, before </body>
<TanStackRouterDevtools position="bottom-right" />
<Scripts />

Unified TanStack Devtools (recommended with multiple TanStack libraries):

If using Start + Query (or other TanStack libraries), use the unified TanStackDevtools shell instead of individual devtools components:

npm install -D @tanstack/react-devtools

import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'
import { TanStackDevtools } from '@tanstack/react-devtools'

// In root layout, before </body>
<TanStackDevtools
  config={{ position: 'bottom-right' }}
  plugins={[
    { name: 'TanStack Router', render: <TanStackRouterDevtoolsPanel /> },
    // Add more plugins: Query, etc.
  ]}
/>
<Scripts />

Use *Panel variants (TanStackRouterDevtoolsPanel, ReactQueryDevtoolsPanel) when embedding inside TanStackDevtools.

Rule Categories

Priority	Rule	Description
CRITICAL	sf-server-functions	createServerFn, GET/POST methods, handler pattern
HIGH	sf-middleware	createMiddleware, client/server execution, chaining
HIGH	sf-validation	Input validation with Zod/Standard Schema, trust boundaries
HIGH	ssr-streaming	Streaming SSR with Suspense, TTFB optimization
HIGH	seo-head-management	head() per route, meta tags, HeadContent, OG tags
HIGH	auth-patterns	beforeLoad guards, session server fns, cookie forwarding
MEDIUM	ssr-hydration	Hydration mismatch prevention, client-only components
MEDIUM	ssr-prerendering	Static prerendering, ISR via Cache-Control
MEDIUM	api-routes	createAPIFileRoute, REST handlers, webhooks
MEDIUM	deployment	Hosting adapters, env vars, production config
MEDIUM	config-project-setup	Vite plugin, root route, project structure

Critical Rules

ALWAYS use createServerFn for server-side code

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

const getUser = createServerFn({ method: 'GET' })
  .handler(async () => {
    return db.users.findFirst()
  })

ALWAYS validate server function inputs

const updateUser = createServerFn({ method: 'POST' })
  .inputValidator((data: { name: string; email: string }) => data)
  .handler(async ({ data }) => {
    return db.users.update({ where: { email: data.email }, data })
  })

NEVER access window/document in components rendered on the server

// BAD — hydration mismatch
function Bad() {
  return <span>{window.innerWidth}px</span>
}

// GOOD — use useEffect for client-only state
function Good() {
  const [width, setWidth] = useState<number | null>(null)
  useEffect(() => setWidth(window.innerWidth), [])
  return <span>{width ?? '...'}px</span>
}

ALWAYS use head() for SEO metadata

export const Route = createFileRoute('/about')({
  head: () => ({
    meta: [
      { title: 'About Us' },
      { name: 'description', content: 'Learn about our company' },
    ],
  }),
})

Key Patterns

Auth Guard with Redirect

// routes/_authed.tsx
export const Route = createFileRoute('/_authed')({
  beforeLoad: async ({ location }) => {
    const user = await getCurrentUserFn()
    if (!user) {
      throw redirect({
        to: '/login',
        search: { redirect: location.href },
      })
    }
    return { user }
  },
})

Server Function with Validation

const createPost = createServerFn({ method: 'POST' })
  .inputValidator((data: { title: string; body: string }) => data)
  .handler(async ({ data }) => {
    const post = await db.posts.create({ data })
    return post
  })

Streaming Dashboard

export const Route = createFileRoute('/dashboard')({
  loader: async ({ context: { queryClient } }) => {
    // Await critical data
    await queryClient.ensureQueryData(userQueries.profile())
    // Prefetch non-critical (streams in via Suspense)
    queryClient.prefetchQuery(statsQueries.dashboard())
  },
  component: DashboardPage,
})

function DashboardPage() {
  const { data: user } = useSuspenseQuery(userQueries.profile())
  return (
    <div>
      <Header user={user} />
      <Suspense fallback={<StatsSkeleton />}>
        <DashboardStats />
      </Suspense>
    </div>
  )
}