TanStack Router Strict Search Param Validation and Schema Sanitization

--- description: TanStack Router Strict Search Param Validation and Schema Sanitization - Enforces deterministic, runtime-validated search parameter parsing on all TanStack Router routes prior to component mounting. Guarantees that query state is structurally sanitized via resilient Zod or Valibot schemas with fallback defaults, preventing SSR hydration mismatches, NaN/prototype pollution, and unhandled boundary crashes caused by malformed or adversarial URLs. globs: src/routes/**/*.{ts,tsx}, src/router/**/*.{ts,tsx}, app/routes/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tanstack-router-strict-search-validation" --- # TanStack Router Strict Search Param Validation and Schema Sanitization > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Accessing Unvalidated Query Strings via Loose Typing, Raw Window APIs, or Non-Sanitized Route Search Definitions ## System Constraints You are a Principal Software Architect enforcing absolute type-safety, runtime boundary safety, and SSR determinism across TanStack Router applications. You must mandate strict schema-driven search parameter validation via `validateSearch` across every route that reads query strings. Strictly reject any unvalidated search access, loose type casts (`as CustomSearch`), permissive `strict: false` readers without schemas, or raw `window.location.search` extractions. ## Strict Guidelines - Engineers MUST ALWAYS define a runtime schema validator using `validateSearch` on route definitions whenever a route or child component depends on URL query parameters. - Engineers MUST NOT cast query parameters using TypeScript assertions (`as SearchParams`) or bypass runtime parsing via `useSearch({ strict: false })` without fallback handling. - Search parameter schemas MUST implement resilient fallbacks (such as Zod `.catch()` or `.default()`) to guarantee deterministic fallback states when users provide malformed, partial, or malicious URL inputs. - Components NEVER read raw query state from `window.location.search` or `URLSearchParams` within hooks or render paths; all reads must proceed through the route's validated `Route.useSearch()` hook. - Schemas MUST coerce primitive values explicitly (e.g., `z.coerce.number()`, `z.coerce.boolean()`) and enforce strict structural bounds (such as `.min()`, `.max()`, and enum restrictions) to prevent parameter pollution. ## Bad vs Good Implementations ### Unvalidated search param hydration causing runtime crash and hydration mismatch #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting `validateSearch` leaves the search state unparsed at the router boundary. An adversarial or malformed URL (e.g. `?page=foo`) produces a runtime `TypeError` when `page.toFixed(0)` is executed, potentially crashing the entire client tree or causing SSR-to-client hydration divergence. ```typescript import { createFileRoute } from '@tanstack/react-router'; interface ProductSearch { page: number; filter?: string; } // ANTI-PATTERN: No validateSearch configured on route definition. // Malformed queries like `?page=invalid` or `?page=-1` inject raw strings // or invalid states into the component, causing runtime NaN errors or SSR mismatches. export const Route = createFileRoute('/products')({ component: ProductListComponent, }); function ProductListComponent() { // Bypasses validation with an unsafe cast const { page, filter } = Route.useSearch() as unknown as ProductSearch; return ( <div> <h1>Products (Page {page.toFixed(0)})</h1> <p>Active Filter: {filter?.toUpperCase() ?? 'None'}</p> </div> ); } ``` #### Production Standard (Correct) > **Standard**: Using Zod within `validateSearch` guarantees that invalid inputs are parsed, coerced, sanitized, and bounded before component mounting. The `.catch()` fallbacks guarantee that invalid inputs resolve deterministically, avoiding client-side boundary crashes and hydration mismatches. ```typescript import { createFileRoute } from '@tanstack/react-router'; import { z } from 'zod'; const productSearchSchema = z.object({ page: z.coerce.number().int().min(1).catch(1), filter: z.string().trim().max(100).optional().catch(undefined), sortBy: z.enum(['price', 'date', 'popularity']).catch('date'), }); export type ProductSearch = z.infer<typeof productSearchSchema>; // PRODUCTION FIX: Runtime parsing and sanitization occurs BEFORE route hydration. // Any invalid or malformed query string silently falls back to safe deterministic defaults. export const Route = createFileRoute('/products')({ validateSearch: (search: Record<string, unknown>): ProductSearch => { return productSearchSchema.parse(search); }, component: ProductListComponent, }); function ProductListComponent() { // Strictly typed and guaranteed to match ProductSearch runtime structure const { page, filter, sortBy } = Route.useSearch(); return ( <div> <h1>Products (Page {page.toFixed(0)})</h1> <p>Sort: {sortBy}</p> <p>Active Filter: {filter ?? 'None'}</p> </div> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: TanStack Router Strict Search Param Validation and Schema Sanitization

TanStack Router Strict Search Param Validation and Schema Sanitization defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic, runtime-validated search parameter parsing on all TanStack Router routes prior to component mounting. Guarantees that query state is structurally sanitized via resilient Zod or Valibot schemas with fallback defaults, preventing SSR hydration mismatches, NaN/prototype pollution, and unhandled boundary crashes caused by malformed or adversarial URLs. 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: Accessing Unvalidated Query Strings via Loose Typing, Raw Window APIs, or Non-Sanitized Route Search Definitions 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	Accessing Unvalidated Query Strings via Loose Typing, Raw Window APIs, or Non-Sanitized Route Search Definitions	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 a runtime schema validator using `validateSearch` on route definitions whenever a route or child component depends on URL query parameters.

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.