TanStack Start Invariants: Type-Safe Search Params, Server Functions, and Deferred Streaming

--- description: TanStack Start Invariants: Type-Safe Search Params, Server Functions, and Deferred Streaming - Mandates strict schema-validated search parameters, isolated server functions via createServerFn, and explicit stream deferral via defer() and Await for non-critical loader promises in TanStack Start SSR. Violating these patterns degrades Time to First Byte (TTFB), causes hydration mismatches, and risks leaking server secrets to the client bundle. globs: app/**/*.{ts,tsx}, src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tanstack-start-ssr-streaming-search-params-standard" --- # TanStack Start Invariants: Type-Safe Search Params, Server Functions, and Deferred Streaming > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Blocking TTFB via Monolithic Loaders and Bypassing Search Param Schema Validation ## System Constraints You are a Principal Software Architect enforcing production invariants for TanStack Start and TanStack Router fullstack SSR. You enforce zero-compromise type safety for search params via schemas, boundary isolation with createServerFn, and non-blocking streaming SSR via defer() and <Await>. ## Strict Guidelines - Engineers MUST ALWAYS validate route search parameters using `validateSearch` with a runtime schema validator (e.g., Zod, ArkType, or Valibot) on `createFileRoute` definitions. - Engineers MUST NOT access `window.location.search` or read unvalidated search parameters with `useSearch({ strict: false })` in client components. - Loaders MUST NOT await slow or secondary I/O operations directly on the critical SSR render path; non-critical promises MUST be wrapped with `defer()` and resolved asynchronously on the client. - Deferred promises MUST be consumed using `<Suspense>` boundaries coupled with the `<Await promise={...}>` component to prevent streaming deadlocks and layout shift. - Server-side mutations and direct database queries MUST be encapsulated inside `createServerFn({ method: 'GET' | 'POST' })` to guarantee boundary tree-shaking and prevent server secret leakage. - Components NEVER execute client-side data fetching hooks (e.g., raw `useEffect`) for data that belongs to the initial route state; all initial route state must be initialized through the route `loader`. - Loaders returning serializable state MUST ensure all returned properties are JSON-compatible; non-serializable classes or circular references MUST NOT be passed from SSR loaders. ## Bad vs Good Implementations ### Search Parameter Validation & Type-Safe Consumption #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting validateSearch causes runtime fragility, lacks default fallbacks, and strips TypeScript compile-time guarantees from Route.useSearch and navigation links. ```typescript import { createFileRoute } from '@tanstack/react-router'; // ANTI-PATTERN: No validateSearch defined, consuming unvalidated search state export const Route = createFileRoute('/dashboard')({ component: DashboardComponent, }); function DashboardComponent() { // Runtime error-prone and untyped; page and filter can be undefined or malicious injection const { page, filter } = Route.useSearch({ strict: false }) as any; return ( <div> Page: {page} Filter: {filter} </div> ); } ``` #### Production Standard (Correct) > **Standard**: Validates incoming query parameters against a Zod schema with resilient defaults, producing strictly typed search params in useSearch and throughout the router tree. ```typescript import { createFileRoute } from '@tanstack/react-router'; import { z } from 'zod'; const searchSchema = z.object({ page: z.number().catch(1).default(1), filter: z.string().optional().default(''), }); type SearchParams = z.infer<typeof searchSchema>; export const Route = createFileRoute('/dashboard')({ validateSearch: (search: Record<string, unknown>): SearchParams => { return searchSchema.parse(search); }, component: DashboardComponent, }); function DashboardComponent() { const { page, filter } = Route.useSearch(); return ( <div> Page: {page} Filter: {filter} </div> ); } ``` ### SSR Server Functions with Deferred Streaming #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Imports server DB directly into route file, and awaits slow metrics directly in loader, freezing HTML response generation and degrading TTFB across the application. ```typescript import { createFileRoute } from '@tanstack/react-router'; import { db } from '~/server/db'; // DANGER: Leaks server dependencies into client bundle export const Route = createFileRoute('/analytics')({ loader: async () => { // ANTI-PATTERN: Awaiting a slow query directly blocks the initial TTFB on SSR const criticalUser = await db.user.findFirst(); const slowMetrics = await db.metrics.aggregateHeavy(); return { user: criticalUser, metrics: slowMetrics, }; }, component: AnalyticsComponent, }); ``` #### Production Standard (Correct) > **Standard**: Uses createServerFn to isolate server logic, awaits only critical path user data for swift TTFB, and wraps slow data in defer() and <Await> with Suspense for non-blocking streaming. ```typescript import { createFileRoute, defer, Await } from '@tanstack/react-router'; import { createServerFn } from '@tanstack/start'; import { Suspense } from 'react'; const getCriticalUser = createServerFn({ method: 'GET' }).handler(async () => { const { db } = await import('~/server/db'); return db.user.findFirstOrThrow(); }); const getHeavyMetrics = createServerFn({ method: 'GET' }).handler(async () => { const { db } = await import('~/server/db'); return db.metrics.aggregateHeavy(); }); export const Route = createFileRoute('/analytics')({ loader: async () => { const user = await getCriticalUser(); // Fast-path HTML stream: defer heavy background promise const slowMetricsPromise = getHeavyMetrics(); return { user, deferredMetrics: defer(slowMetricsPromise), }; }, component: AnalyticsComponent, }); function AnalyticsComponent() { const { user, deferredMetrics } = Route.useLoaderData(); return ( <main> <h1>Welcome, {user.name}</h1> <Suspense fallback={<div>Loading heavy metrics...</div>}> <Await promise={deferredMetrics}> {(metrics) => <pre>{JSON.stringify(metrics, null, 2)}</pre>} </Await> </Suspense> </main> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: TanStack Start Invariants: Type-Safe Search Params, Server Functions, and Deferred Streaming

TanStack Start Invariants: Type-Safe Search Params, Server Functions, and Deferred Streaming defines an industrial-grade behavioral standard for frontend engineering. Mandates strict schema-validated search parameters, isolated server functions via createServerFn, and explicit stream deferral via defer() and Await for non-critical loader promises in TanStack Start SSR. Violating these patterns degrades Time to First Byte (TTFB), causes hydration mismatches, and risks leaking server secrets to the client bundle. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Blocking TTFB via Monolithic Loaders and Bypassing Search Param Schema Validation Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Blocking TTFB via Monolithic Loaders and Bypassing Search Param Schema Validation	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS validate route search parameters using `validateSearch` with a runtime schema validator (e.g., Zod, ArkType, or Valibot) on `createFileRoute` definitions.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.