* 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>
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 staystruefor 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:
- Security: the value can be inlined into the client bundle.
- 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
undefinedeven 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()orcreateServerFn() - 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.