TanStack Router v1 Runtime Search Parameter Validation and Isolation Invariant

--- description: TanStack Router v1 Runtime Search Parameter Validation and Isolation Invariant - Enforces strict runtime schema validation and serialization isolation for all route search parameters via validateSearch at the route boundary. Eliminates client-side prototype pollution, malformed state propagation, and unchecked type-casting across nested route transitions. globs: src/routes/**/*.{ts,tsx}, src/router/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tanstack-router-v1-search-param-schema-invariant" --- # TanStack Router v1 Runtime Search Parameter Validation and Isolation Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Bypassing runtime validation via TypeScript type assertions or unconstrained record parsing in route search configurations ## System Constraints You are a Principal Software Architect enforcing runtime boundary safety in TanStack Router v1. You MUST reject any route search parameter implementation that uses raw type assertions (e.g., 'as ProductSearch'), omits schema-based parsing (Zod, Valibot, or ArkType), or allows arbitrary prototype keys to penetrate the route state tree. Mandate deterministic fallback defaults and stripped unknown keys on every route search parameter contract. ## Strict Guidelines - Engineers MUST ALWAYS define route search parameters using an explicit runtime validation schema (e.g., Zod, Valibot, ArkType) within the validateSearch property of createFileRoute or createRoute. - Engineers MUST NOT perform raw type assertions (e.g., `validateSearch: (raw: Record<string, unknown>) => raw as SearchParams`) which bypass runtime parsing and allow malformed query values. - Engineers MUST explicitly strip or reject undeclared keys in the schema (e.g., `z.object({...}).strip()`) to guard against client-side prototype pollution and parameter pollution attacks. - Code SHOULD leverage standard adapter utilities (such as `zodValidator` from `@tanstack/zod-adapter` or direct `.parse()` implementations with fallback error boundaries) to guarantee idempotent serialization. - Components NEVER read search parameters directly from `window.location.search` or `new URLSearchParams()`; they MUST use TanStack Router's `Route.useSearch()` or `useSearch({ from: ... })` hooks. - Services MUST ensure that numeric and boolean search parameters define explicit coercions (e.g., `z.coerce.number()`) or fallback defaults to maintain valid state transitions on empty or malformed inputs. ## Bad vs Good Implementations ### Unsafe Type-Cast Search Parameter Definition vs Strict Zod Schema Validation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using type casting (`search as unknown as InventorySearch`) completely bypasses runtime validation. If a user modifies the URL to `?page=invalid&sort=malicious&__proto__[polluted]=true`, the application accepts these parameters unparsed, leading to runtime TypeErrors and state-space vulnerabilities. ```typescript import { createFileRoute } from '@tanstack/react-router'; interface InventorySearch { page: number; filter?: string; sort: 'asc' | 'desc'; } // CRITICAL FLAW: Runtime bypass allows prototype pollution, NaN injection, and invalid enum values export const Route = createFileRoute('/inventory')({ validateSearch: (search: Record<string, unknown>): InventorySearch => { return search as unknown as InventorySearch; }, component: InventoryComponent, }); function InventoryComponent() { const { page, sort } = Route.useSearch(); // Runtime crash if page is undefined or string ('abc'.toFixed() throws TypeError) return <div>Page: {page.toFixed(0)}, Sort: {sort.toUpperCase()}</div>; } ``` #### Production Standard (Correct) > **Standard**: The schema parses, coerces, and strips unknown keys at the route boundary. Malformed parameters fall back gracefully via `.catch(...)`, ensuring `page` is consistently a positive integer and `sort` is strictly checked, fully immunizing the component from runtime exceptions and prototype pollution. ```typescript import { createFileRoute } from '@tanstack/react-router'; import { z } from 'zod'; const inventorySearchSchema = z.object({ page: z.coerce.number().int().positive().catch(1), filter: z.string().trim().optional(), sort: z.enum(['asc', 'desc']).catch('asc'), }).strip(); export type InventorySearch = z.infer<typeof inventorySearchSchema>; export const Route = createFileRoute('/inventory')({ validateSearch: (rawSearch: Record<string, unknown>): InventorySearch => { return inventorySearchSchema.parse(rawSearch); }, component: InventoryComponent, }); function InventoryComponent() { const { page, sort, filter } = Route.useSearch(); return ( <div> Page: {page.toFixed(0)}, Sort: {sort.toUpperCase()} {filter ? ` (Filter: ${filter})` : null} </div> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: TanStack Router v1 Runtime Search Parameter Validation and Isolation Invariant

TanStack Router v1 Runtime Search Parameter Validation and Isolation Invariant defines an industrial-grade behavioral standard for frontend engineering. Enforces strict runtime schema validation and serialization isolation for all route search parameters via validateSearch at the route boundary. Eliminates client-side prototype pollution, malformed state propagation, and unchecked type-casting across nested route transitions. 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: Bypassing runtime validation via TypeScript type assertions or unconstrained record parsing in route search configurations 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	Bypassing runtime validation via TypeScript type assertions or unconstrained record parsing in route search configurations	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 define route search parameters using an explicit runtime validation schema (e.g., Zod, Valibot, ArkType) within the validateSearch property of createFileRoute or createRoute.

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.