TanStack Start SSR Loaders, Type-Safe Search Params, and Deferred Streaming Standard

--- description: TanStack Start SSR Loaders, Type-Safe Search Params, and Deferred Streaming Standard - Enforces strict type-safe search parameter validation using schema validators, mandates clear separation between critical render-blocking data and deferred streaming promises in SSR loaders, and isolates server operations via createServerFn. This prevents hydration mismatches, client-bundle server secret leaks, and severe TTFB degradation during server-side rendering. globs: src/routes/**/*.{ts,tsx}, src/server/**/*.{ts,tsx}, app/routes/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tanstack-start-ssr-loader-streaming-guardrail" --- # TanStack Start SSR Loaders, Type-Safe Search Params, and Deferred Streaming Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Blocking SSR pipelines with un-deferred waterfalls, unvalidated raw URL queries, and client-leaked server data fetching. ## System Constraints You are a Principal Software Architect enforcing TanStack Start and TanStack Router SSR standards. You must strictly reject routes with unvalidated search params, monolithic blocking loaders, direct database/server imports inside client routes without createServerFn, or improper consumption of deferred streaming data without Await and Suspense boundaries. ## Strict Guidelines - Engineers MUST ALWAYS validate route search parameters using `validateSearch` with a valid schema validator (e.g., Zod, Standard Schema) on `createFileRoute`. - Engineers MUST NOT block critical SSR page rendering by awaiting non-critical, slow, or secondary asynchronous requests directly in route `loader` functions. - Code SHOULD defer slow data by returning raw unresolved promises or utilizing `defer()` in `loader`, resolving them in UI components wrapped with `<Suspense>` and `<Await>`. - Services MUST encapsulate direct database, filesystem, or private API calls inside `createServerFn` to guarantee dead-code elimination and prevent server secret leakage into client bundles. - Components NEVER read raw `window.location.search` or `useLocation().search`; they MUST consume validated parameters via `Route.useSearch()` to guarantee compile-time type safety. ## Bad vs Good Implementations ### Search Validation, createServerFn Isolation, and Deferred SSR Streaming #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly importing `db` leaks server drivers into the client compilation bundle. Lacking `validateSearch` makes URL state vulnerable to runtime crashes and injection. Awaiting `slowAnalytics` blocks server-side rendering entirely, degrading Time to First Byte (TTFB). ```typescript import { createFileRoute } from '@tanstack/react-router'; import { db } from '@/server/db'; // FATAL: Bundles server driver into client build export const Route = createFileRoute('/dashboard')({ // Flaw 1: No validateSearch provided; search params are untyped and unvalidated loader: async ({ search }: { search: any }) => { // Flaw 2: Direct server database access in route file const user = await db.user.findUnique({ where: { id: search.userId } }); // Flaw 3: Blocking slow 3rd-party fetch degrades SSR TTFB for the entire page const slowAnalytics = await fetch('https://api.analytics.internal/heavy-report').then(r => r.json()); return { user, slowAnalytics, }; }, component: () => { const { user, slowAnalytics } = Route.useLoaderData(); return ( <div> <h1>Welcome {user.name}</h1> <pre>{JSON.stringify(slowAnalytics)}</pre> </div> ); }, }); ``` #### Production Standard (Correct) > **Standard**: Validates search parameters using Zod. Isolates server logic inside `createServerFn`. Awaits critical initial paint data (`user`) while deferring slow non-critical data (`deferredAnalytics`), which is streamed via `<Suspense>` and `<Await>` without delaying initial SSR response. ```typescript import { createFileRoute, Await } from '@tanstack/react-router'; import { createServerFn } from '@tanstack/start'; import { Suspense } from 'react'; import { z } from 'zod'; const dashboardSearchSchema = z.object({ userId: z.string().min(1), tab: z.enum(['overview', 'metrics']).default('overview'), }); // Isolated server function guarantees code separation across SSR/Client boundaries const fetchDashboardData = createServerFn({ method: 'GET' }) .validator((params: { userId: string }) => params) .handler(async ({ data: { userId } }) => { const { db } = await import('@/server/db'); const user = await db.user.findUnique({ where: { id: userId } }); if (!user) throw new Error('User not found'); return user; }); const fetchSlowAnalytics = createServerFn({ method: 'GET' }).handler(async () => { const res = await fetch('https://api.analytics.internal/heavy-report'); return res.json() as Promise<{ summary: string }>; }); export const Route = createFileRoute('/dashboard')({ validateSearch: (search) => dashboardSearchSchema.parse(search), loader: async ({ search }) => { // Critical data awaited for immediate SSR paint const user = await fetchDashboardData({ data: { userId: search.userId } }); // Slow data deferred as a raw promise for streaming const deferredAnalytics = fetchSlowAnalytics(); return { user, deferredAnalytics, }; }, component: DashboardComponent, }); function DashboardComponent() { const { user, deferredAnalytics } = Route.useLoaderData(); const { tab } = Route.useSearch(); return ( <main> <h1>Welcome, {user.name} (Tab: {tab})</h1> <Suspense fallback={<div>Streaming analytics...</div>}> <Await promise={deferredAnalytics}> {(analytics) => <pre>{JSON.stringify(analytics, null, 2)}</pre>} </Await> </Suspense> </main> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: TanStack Start SSR Loaders, Type-Safe Search Params, and Deferred Streaming Standard

TanStack Start SSR Loaders, Type-Safe Search Params, and Deferred Streaming Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict type-safe search parameter validation using schema validators, mandates clear separation between critical render-blocking data and deferred streaming promises in SSR loaders, and isolates server operations via createServerFn. This prevents hydration mismatches, client-bundle server secret leaks, and severe TTFB degradation during server-side rendering. 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 SSR pipelines with un-deferred waterfalls, unvalidated raw URL queries, and client-leaked server data fetching. 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 SSR pipelines with un-deferred waterfalls, unvalidated raw URL queries, and client-leaked server data fetching.	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 valid schema validator (e.g., Zod, Standard Schema) on `createFileRoute`.

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.