TanStack Start (React) — RC-Ready Playbook

Full-stack React on TanStack Router with per-route SSR/CSR, file-based routing, server functions, and first-class Cloudflare Workers support.

Use this skill when

• Building a greenfield React app that needs route-level SSR/CSR/SSG switches.
• Migrating from Next.js/React Router while keeping file-based routing + API routes.
• Shipping to edge runtimes (Workers) with typed server functions and bindings.
• You want predictable routing with type-safe params/search + built-in preloading.

What’s inside

• References: quickstart/layout, rendering modes, server functions, Cloudflare hosting, execution/auth, plus new routing/data/navigation/devtools guides.
• Script:

  scripts/bootstrap-cloudflare-start.sh <app>

  scaffolds Start + Workers + binding types.
• Troubleshooting: hydration, API routing, bindings, navigation/preloading failures.

---

Quick Start (React)

npm create @tanstack/start@latest my-app
cd my-app
npm run dev

Manual installs (all bundle targets are supported): add

@tanstack/react-router

+

@tanstack/react-start

with your bundler plugin (

vite

,

webpack

, or

esbuild

) per the official install guides.

Core layout reminder

• app/routes/**

  file-based routes → router tree, automatic code-splitting + data preloading.

• app/entry.client.tsx

  hydrates

  <StartClient />

  ;

  app/entry.server.tsx

  wraps

  createServerEntry

  .

• app/config.ts

  or

  app/start.ts

  sets

  defaultSsr

  ,

  spaMode

  , middleware, and context.

---

Routing + Data Best Practices

• Type-safe params & search:

  createFileRoute()

  infers path params; add

  validateSearch

  (zod) to parse and coerce search params.
• Route matching order is deterministic (index → static → dynamic → splat); rely on this when adding catch-alls.
• Loaders run once per location change; return plain data, throw

  redirect()

  /

  notFound()

  for control flow.
• Data mutations: colocate

  action

  /server functions; keep loaders read-only and invalidate via

  router.invalidate()

  after mutation.
• TanStack Query bridge: create a

  QueryClient

  in router context and

  ensureQueryData

  inside loaders to dedupe fetches.
• Deferred/external data: stream partial data or read from external loaders; prefer suspense-friendly responses.
• Head management: set

  head

  per route for

  <title>

  /meta; derive from loader data to keep SEO consistent.
• Not-found/auth: throw

  notFound()

  or

  redirect()

  in loaders/middleware; use error boundaries for UX.

Example route (typed search + data-only SSR):

// app/routes/posts.$postId.tsx
import { createFileRoute, redirect } from '@tanstack/react-router'
import { z } from 'zod'

export const Route = createFileRoute('/posts/$postId')({
  validateSearch: z.object({ preview: z.boolean().optional() }),
  ssr: 'data-only',
  loader: async ({ params, search, context }) => {
    const post = await context.queryClient.ensureQueryData(['post', params.postId], () =>
      fetch(`/api/posts/${params.postId}?preview=${!!search.preview}`).then(r => r.json())
    )
    if (!post.published && !search.preview) throw redirect({ to: '/drafts' })
    return { post }
  },
})

---

Navigation, Preloading, and UX

• Link prefetch defaults:

  <Link preload="intent">

  (hover/focus) preloads route data/code; use

  preload="render"

  for above-the-fold routes.
• Programmatic preloading:

  router.preloadRoute({ to, search })

  to warm caches before navigation (e.g., on visibility).
• Route masking: keep canonical URLs while showing user-friendly masks (e.g.,

  /products?slug=abc

  masked as

  /p/abc

  ).
• Navigation blocking: protect unsaved forms with

  router.navigate({ to, replace, from })

  blockers or

  useBlocker

  .
• Scroll restoration: enable

  scrollRestoration

  to restore positions on back/forward; customize per route when using long lists.
• Search param serialization: customize parse/stringify to keep numbers/dates stable and avoid stringified booleans.

---

Rendering & Performance

• Per-route SSR: set

  ssr: true | false | 'data-only'

  on routes;

  defaultSsr

  config sets the baseline.
• Code-splitting: file-based routes auto-split; add

  lazy

  /

  load

  for manual chunks on code-based routes.
• Preloading strategy: pair

  preload="intent"

  links with

  defaultPreloadStaleTime

  to avoid over-fetching.
• Render optimizations: keep loaders pure, memoize heavy components, and use

  pendingComponent

  for CSR routes to avoid layout shift.

---

Devtools, Linting, and LLM Support

• Add

  <RouterDevtools />

  during development to inspect matches, loader states, and preloading.
• Enable the ESLint plugin

  @tanstack/eslint-plugin-router

  with the recommended config to enforce inference-sensitive property order (e.g.,

  beforeLoad

  before

  loader

  ).
• LLM-aware routing: the Router exposes structured route metadata to LLM agents; keep descriptions concise in

  Route

  meta for better AI navigation.

---

Deployment Notes (Cloudflare-friendly)

• Keep

  cloudflare({ viteEnvironment: { name: 'ssr' } })

  first in Vite plugins so bindings reach server entry.
• Regenerate bindings after changes:

  npm run cf-typegen

  .
• For static-heavy sites, enable prerender to ship HTML to Workers Assets/Pages; exclude param routes or add explicit

  pages

  .

---

Ship Checklist

• Routes load without hydration warnings (prefer

  ssr: 'data-only'

  for non-deterministic UI).
• Search params validated with

  validateSearch

  and custom serializer where needed.
• Link preloading configured for high-traffic routes; blockers added for unsaved forms.
• ESLint plugin enabled (

  create-route-property-order

  rule) and

  npm run check

  passes.
• Devtools verified locally;

  router.matches

  state looks correct.
• Cloudflare bindings typed (

  cf-typegen

  ) and streaming tested via

  curl -N

  .