0
Fork 0
mirror of https://github.com/TanStack/router.git synced 2026-11-16 19:38:07 +00:00
router/docs/start/framework/react/guide/execution-model.md
Tanner Linsley 3526194849
docs(skills): address 8 agent failure modes from user feedback (#7314)
* docs(skills): address 8 agent failure modes from external feedback

Adds new start-core/auth-server-primitives skill (sessions, cookies,
OAuth+PKCE, password-reset enumeration defense, CSRF, rate limiting,
session rotation) and updates 8 existing skills + matching docs to fix
patterns where agents produce insecure or wrong-framework output.

Skill changes:
- new: start-core/auth-server-primitives (server half of auth)
- router-core/auth-and-guards: route guard != RPC guard
- start-core/server-functions: wrong import path, RPC auth required,
  Cache-Control public is a cross-tenant leak, wrong-framework patterns
- start-core/middleware: wrong import path, sendContext shape vs access
  (3-layer wrong/still-wrong/correct), authMiddleware framing
- start-core/execution-model: file markers (server-only/client-only),
  module-level process.env is undefined under Worker SSR
- start-core/deployment: cloudflare env-at-request-time
- router-core/ssr: wrong file structures (next.js, react-router-dom)
- router-core/type-safety: wrong-framework imports + structures

Docs updated to mirror each skill change so source-of-truth and the
intent-indexed skill stay in sync. New authentication-server-primitives
guide is the long-form companion to the new skill.

intent validate: 30 skill files pass (was 29).

* ci: apply automated fixes

* docs(skills): address coderabbit review feedback

- Fix internal docs links to use correct relative paths instead of an
  absolute /start/latest/... URL and missing one ../ segment
- Remove blank line inside auth-and-guards blockquote (markdownlint MD028)
- Restore overload pattern in type-safety ValidateNavigateOptions and
  ValidateRedirectOptions examples; the casts I had introduced stripped
  generic context and contradicted the skill's own no-cast rule
- Add db.sessions.revokeAllForUser before create in login rotation
  snippets so the example matches the prose
- Soften useServerFn guidance: it's required only when the server
  function throws redirect/notFound; plain-data calls work directly and
  via useMutation/useQuery

* ci: apply automated fixes

* docs(skills): compress type-safety to stay under 500-line cap

Prettier's autofix expanded my single-line overload signatures across
multiple lines, pushing the file over the 500-line limit. Drop the
redundant fetchOrRedirect example (same pattern as useDelayedNavigate)
and describe ValidateRedirectOptions usage in prose instead.

* docs(skills): CSRF origin check should compare full origin, not host alone

Comparing only new URL(origin).host against APP_HOST silently accepts a
mismatched scheme — http://example.com would pass a check meant for
https://example.com. Compare the full origin (scheme + host + port)
against APP_ORIGIN instead. Same fix in skill and docs.

* docs(skills): make useDelayedNavigate callback truly return void

The callback returned the result of setTimeout (a timer handle), not
void as the public overload's return type implied. Wrap in a block so
the example matches the declared return type.

Skipped the related nitpick to add a separate redirect example — the
existing prose already describes the same overload pattern, and a
duplicate example would push the file close to the 500-line cap that
prettier autofix has been bumping us against.

* docs(skills): fix two real bugs in auth-server-primitives examples

1. Cookie parser truncated values containing '='. Signed cookies, JWTs,
   and base64-padded values all use '='. Use indexOf to split on the
   FIRST '=' only.

2. Login example short-circuited verifyPasswordHash on user-not-found,
   contradicting the prose's "same time, same error" claim — the
   no-user branch returned instantly while wrong-password spent ~100ms
   hashing, leaking account existence over the wire. Always verify
   against a hash; use a precomputed DUMMY_PASSWORD_HASH when the user
   is missing, then combine with the user-exists bit for the final ok.

Same fixes in the SKILL.md and the docs companion.

* docs(skills): address manuel's review on react-specific guides

- middleware.md, server-functions.md: drop cross-framework <framework>
  placeholders; this is the React-specific guide, just say
  @tanstack/react-start
- execution-model.md: drop the same trailing line about solid-start /
  vue-start paths
- hosting.md: remove the Cloudflare env-handling subsection — the
  general per-request rule lives in environment-variables.md and
  doesn't need to be repeated under a specific host
- environment-variables.md: mention the cloudflare:workers env binding
  as the canonical Cloudflare way to read env (including module scope),
  per Manuel's link to the Cloudflare docs
- deployment skill: same upgrade — show the cloudflare:workers env
  pattern alongside the per-request handler approach

* docs(skills): drop redundant server-only marker in session example

The file already imports from @tanstack/react-start/server, which is
on import protection's default client-deny specifier list. The
side-effect marker is redundant — drop it. Same fix in skill and docs.

* docs(skills): drop wrong-import-path mistakes — TS already catches them

Manuel pointed out that TypeScript catches both common wrong paths:
'@tanstack/react-router' has no exported member createServerFn /
createMiddleware, and '@tanstack/start' is "Cannot find module". Skill
space is precious; the items don't earn their slot if tsc handles them.

Removed:
- Common Mistake "Wrong import path" from server-functions and
  middleware skills (renumbered the remaining mistakes)
- The matching top-of-file CRITICAL line in both skills
- The "Import path" callouts in the middleware and server-functions
  docs

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
2026-05-02 23:11:30 -06:00

11 KiB

id title
execution-model Execution Model

Understanding where code runs is fundamental to building TanStack Start applications. This guide explains TanStack Start's execution model and how to control where your code executes.

Core Principle: Isomorphic by Default

All code in TanStack Start is isomorphic by default - it runs and is included in both server and client bundles unless explicitly constrained.

// ✅ This runs on BOTH server and client
function formatPrice(price: number) {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: 'USD',
  }).format(price)
}

// ✅ Route loaders are ISOMORPHIC
export const Route = createFileRoute('/products')({
  loader: async () => {
    // This runs on server during SSR AND on client during navigation
    const response = await fetch('/api/products')
    return response.json()
  },
})

Critical Understanding: Route loaders are isomorphic - they run on both server and client, not just the server.

The Execution Boundary

TanStack Start applications run in two environments:

Server Environment

  • Node.js runtime with access to file system, databases, environment variables
  • During SSR - Initial page renders on server
  • API requests - Server functions execute server-side
  • Build time - Static generation and pre-rendering

Client Environment

  • Browser runtime with access to DOM, localStorage, user interactions
  • After hydration - Client takes over after initial server render
  • Navigation - Route loaders run client-side during navigation
  • User interactions - Event handlers, form submissions, etc.

Execution Control APIs

Server-Only Execution

API Use Case Client Behavior
createServerFn() RPC calls, data mutations Network request to server
createServerOnlyFn(fn) Utility functions Throws error
import { createServerFn, createServerOnlyFn } from '@tanstack/react-start'

// RPC: Server execution, callable from client
const updateUser = createServerFn({ method: 'POST' })
  .inputValidator((data: UserData) => data)
  .handler(async ({ data }) => {
    // Only runs on server, but client can call it
    return await db.users.update(data)
  })

// Utility: Server-only, client crashes if called
const getEnvVar = createServerOnlyFn(() => process.env.DATABASE_URL)

Client-Only Execution

API Use Case Server Behavior
createClientOnlyFn(fn) Browser utilities Throws error
<ClientOnly> Components needing browser APIs Renders fallback
import { createClientOnlyFn } from '@tanstack/react-start'
import { ClientOnly } from '@tanstack/react-router'

// Utility: Client-only, server crashes if called
const saveToStorage = createClientOnlyFn((key: string, value: any) => {
  localStorage.setItem(key, JSON.stringify(value))
})

// Component: Only renders children after hydration
function Analytics() {
  return (
    <ClientOnly fallback={null}>
      <GoogleAnalyticsScript />
    </ClientOnly>
  )
}

useHydrated Hook

For more granular control over hydration-dependent behavior, use the useHydrated hook. It returns a boolean indicating whether the client has been hydrated:

import { useHydrated } from '@tanstack/react-router'

function TimeZoneDisplay() {
  const hydrated = useHydrated()
  const timeZone = hydrated
    ? Intl.DateTimeFormat().resolvedOptions().timeZone
    : 'UTC'

  return <div>Your timezone: {timeZone}</div>
}

Behavior:

  • During SSR: Always returns false
  • First client render: Returns false
  • After hydration: Returns true (and stays true for all subsequent renders)

This is useful when you need to conditionally render content based on client-side data (like browser timezone, locale, or localStorage) while providing a sensible fallback for server rendering.

Environment-Specific Implementations

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

// Different implementation per environment
const getDeviceInfo = createIsomorphicFn()
  .server(() => ({ type: 'server', platform: process.platform }))
  .client(() => ({ type: 'client', userAgent: navigator.userAgent }))

Architectural Patterns

Progressive Enhancement

Build components that work without JavaScript and enhance with client-side functionality:

function SearchForm() {
  const [query, setQuery] = useState('')

  return (
    <form action="/search" method="get">
      <input
        name="q"
        value={query}
        onChange={(e) => setQuery(e.target.value)}
      />
      <ClientOnly fallback={<button type="submit">Search</button>}>
        <SearchButton onSearch={() => search(query)} />
      </ClientOnly>
    </form>
  )
}

Environment-Aware Storage

const storage = createIsomorphicFn()
  .server((key: string) => {
    // Server: File-based cache
    const fs = require('node:fs')
    return JSON.parse(fs.readFileSync('.cache', 'utf-8'))[key]
  })
  .client((key: string) => {
    // Client: localStorage
    return JSON.parse(localStorage.getItem(key) || 'null')
  })

RPC vs Direct Function Calls

Understanding when to use server functions vs server-only functions:

// createServerFn: RPC pattern - server execution, client callable
const fetchUser = createServerFn().handler(async () => await db.users.find())

// Usage from client component:
const user = await fetchUser() // ✅ Network request

// createServerOnlyFn: Crashes if called from client
const getSecret = createServerOnlyFn(() => process.env.SECRET)

// Usage from client:
const secret = getSecret() // ❌ Throws error

Common Anti-Patterns

Module-Level process.env Reads

Reading process.env at module scope is wrong for two reasons, not one:

  1. Security: the value can be inlined into the client bundle.
  2. Runtime correctness: on Cloudflare Workers and other edge SSR runtimes, env is injected per-request. Module-level code runs at module load, before the env exists, so the read evaluates to undefined even on the server.
// ❌ Leaks to client AND is undefined under Worker SSR
const apiKey = process.env.SECRET_KEY

// ✅ Wrap in a server-only function — read happens per call, on the server
const apiKey = createServerOnlyFn(() => process.env.SECRET_KEY)

// ✅ Or read directly inside `.handler()` / middleware `.server()` / server-route handlers
const fetchData = createServerFn().handler(async () => {
  const apiKey = process.env.SECRET_KEY
  // ...
})

Incorrect Loader Assumptions

// ❌ Assuming loader is server-only
export const Route = createFileRoute('/users')({
  loader: () => {
    // This runs on BOTH server and client!
    const secret = process.env.SECRET // Exposed to client
    return fetch(`/api/users?key=${secret}`)
  },
})

// ✅ Use server function for server-only operations
const getUsersSecurely = createServerFn().handler(() => {
  const secret = process.env.SECRET // Server-only
  return fetch(`/api/users?key=${secret}`)
})

export const Route = createFileRoute('/users')({
  loader: () => getUsersSecurely(), // Isomorphic call to server function
})

Hydration Mismatches

// ❌ Different content server vs client
function CurrentTime() {
  return <div>{new Date().toLocaleString()}</div>
}

// ✅ Consistent rendering
function CurrentTime() {
  const [time, setTime] = useState<string>()

  useEffect(() => {
    setTime(new Date().toLocaleString())
  }, [])

  return <div>{time || 'Loading...'}</div>
}

Manual vs API-Driven Environment Detection

// Manual: You handle the logic
function logMessage(msg: string) {
  if (typeof window === 'undefined') {
    console.log(`[SERVER]: ${msg}`)
  } else {
    console.log(`[CLIENT]: ${msg}`)
  }
}

// API: Framework handles it
const logMessage = createIsomorphicFn()
  .server((msg) => console.log(`[SERVER]: ${msg}`))
  .client((msg) => console.log(`[CLIENT]: ${msg}`))

Marking Whole Files Server- or Client-Only

The .server.* and .client.* filename suffixes opt a file into Start's import protection automatically. When you can't or don't want to rename the file, achieve the same effect with a side-effect import at the top:

// src/lib/secrets.ts (filename can't be *.server.ts)
import '@tanstack/react-start/server-only'

export function getApiKey() {
  return process.env.API_KEY
}
// src/lib/storage.ts
import '@tanstack/react-start/client-only'

export function savePreferences(prefs: Record<string, string>) {
  localStorage.setItem('prefs', JSON.stringify(prefs))
}

Both markers in the same file is an error. Type-only imports are ignored. See the Import Protection guide for the full reference, including dev vs build behavior, configuring deny rules, and reading violation traces.

Architecture Decision Framework

Choose Server-Only when:

  • Accessing sensitive data (environment variables, secrets)
  • File system operations
  • Database connections
  • External API keys

Choose Client-Only when:

  • DOM manipulation
  • Browser APIs (localStorage, geolocation)
  • User interaction handling
  • Analytics/tracking

Choose Isomorphic when:

  • Data formatting/transformation
  • Business logic
  • Shared utilities
  • Route loaders (they're isomorphic by nature)

Security Considerations

Bundle Analysis

Always verify server-only code isn't included in client bundles:

# Analyze client bundle
npm run build
# Check dist/client for any server-only imports

Environment Variable Strategy

  • Client-exposed: Use VITE_ prefix for client-accessible variables
  • Server-only: Access via createServerOnlyFn() or createServerFn()
  • Never expose: Database URLs, API keys, secrets

Error Boundaries

Handle server/client execution errors gracefully:

function ErrorBoundary({ children }: { children: React.ReactNode }) {
  return (
    <ErrorBoundaryComponent
      fallback={<div>Something went wrong</div>}
      onError={(error) => {
        if (typeof window === 'undefined') {
          console.error('[SERVER ERROR]:', error)
        } else {
          console.error('[CLIENT ERROR]:', error)
        }
      }}
    >
      {children}
    </ErrorBoundaryComponent>
  )
}

Understanding TanStack Start's execution model is crucial for building secure, performant, and maintainable applications. The isomorphic-by-default approach provides flexibility while the execution control APIs give you precise control when needed.