start-execution-model

TanStack Start Execution Model

Understanding where code runs is the single most important concept in Start, and the #1 source of AI-generated bugs. Targets @tanstack/react-start v1.166.2.

CRITICAL — everything is isomorphic by default. Every module runs in BOTH the server and client bundles. Route loaders run on both — during SSR AND during client navigation. DB, filesystem, and secrets MUST live inside createServerFn (or createServerOnlyFn), never a bare loader or module scope.

CRITICAL — read process.env per request, not at module scope. Module-level reads (1) can be inlined into the client bundle (secret leak) and (2) are undefined on edge runtimes (Cloudflare Workers inject env at request time).

CRITICAL — VITE_/PUBLIC_ prefixed vars are exposed to the client. Server secrets must have NO public prefix.

Agent Workflow (MANDATORY)

Verify APIs against Context7 (/websites/tanstack_start_framework_react) + Exa before writing boundary code. After changes, run fuse-ai-pilot:sniper.

---

The Boundary APIs at a Glance

API	Use case	Client behavior	Server behavior
createServerFn()	RPC, data, mutations	network request	direct execution
createServerOnlyFn(fn)	server utility	throws	direct execution
createClientOnlyFn(fn)	browser utility	direct execution	throws
createIsomorphicFn()	per-env implementation	.client() impl	.server() impl
<ClientOnly fallback>	browser-only UI	renders children	renders fallback
useHydrated()	post-hydration logic	true after hydrate	false
import '@tanstack/react-start/server-only'	whole file server-only	import denied	allowed
import '@tanstack/react-start/client-only'	whole file client-only	allowed	import denied

All boundary creators are imported from @tanstack/react-start; <ClientOnly> and useHydrated come from @tanstack/react-router.

---

The One Gotcha to Remember

// ❌ WRONG — loader is isomorphic; SECRET ships to the browser
export const Route = createFileRoute('/dashboard')({
  loader: async () => {
    const secret = process.env.API_SECRET // leaked
    return fetch(url, { headers: { Authorization: secret } })
  },
})

// ✅ CORRECT — server-only work behind createServerFn
const getData = createServerFn({ method: 'GET' }).handler(async () => {
  const secret = process.env.API_SECRET // stays on the server
  return fetch(url, { headers: { Authorization: secret } })
})
export const Route = createFileRoute('/dashboard')({ loader: () => getData() })

---

Reference Guide

Topic	Reference	Load when
Why loaders/modules are isomorphic; the mental model	references/isomorphic-by-default.md	deciding server vs client vs both
Each boundary API + import markers + which to pick	references/environment-boundaries.md	choosing an API, marking a file
VITE_/PUBLIC_ vs process.env, per-request reads, runtime vars	references/environment-variables.md	env var undefined / leaked
Complete copy-paste examples of every boundary	references/templates/boundaries.md	writing boundary code

---

Decision Framework

• Server-only (createServerFn / createServerOnlyFn): secrets, DB, filesystem, external API keys.
• Client-only (createClientOnlyFn / <ClientOnly>): DOM, localStorage, geolocation, analytics.
• Isomorphic (default / createIsomorphicFn): formatting, business logic, shared utilities, loaders.

Forbidden

• DB / secrets / filesystem in a bare loader (→ createServerFn).
• process.env at module scope (leak + undefined on edge).
• VITE_/PUBLIC_ prefix on a secret.
• Non-deterministic render output (new Date() directly) → hydration mismatch.
• Dynamic import() of a *.functions.ts server function (bundler issues).