TanStack Router Preload Cache Synchronization and Mutation Invalidation Standards

--- description: TanStack Router Preload Cache Synchronization and Mutation Invalidation Standards - Enforces deterministic loader cache lifecycles, abort signal propagation, and synchronous route invalidation across rapid client transitions in TanStack Router. Prevents race conditions and stale-data read anomalies caused by asynchronous preloads competing with concurrent mutations or fast navigational switches. globs: src/routes/**/*.{ts,tsx}, src/router/**/*.{ts,tsx}, src/features/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tanstack-router-preload-cache-invalidation-invariants" --- # TanStack Router Preload Cache Synchronization and Mutation Invalidation Standards > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unsynchronized In-Flight Route Preloads Overwriting Fresh Mutation State and Creating Stale Loader Anomalies ## System Constraints You are a Principal Software Architect enforcing TanStack Router cache synchronization and navigation invariants. You mandate strict loader lifecycle discipline, requiring explicit AbortSignal forwarding, deterministic preload staleTime configurations, and transactional router cache invalidation across all state-mutating transitions. ## Strict Guidelines - Engineers MUST ALWAYS forward the Route loader's `abortController.signal` directly to downstream fetch clients or TanStack Query options to cancel stale in-flight preloads on route transitions. - Engineers MUST ALWAYS invoke `await router.invalidate()` immediately following mutations that affect server state to flush stale preloaded route loader caches across active and background route branches. - Engineers MUST NOT rely on default router cache lifetimes for volatile domain entities; Route definitions MUST explicitly define `staleTime`, `preloadStaleTime`, and `gcTime` matching the underlying data lifecycle. - Loaders integrated with TanStack Query MUST use `queryClient.ensureQueryData()` instead of `queryClient.fetchQuery()` to prevent duplicate requests and prevent preloader race conditions during route hovers. - Route components NEVER should read loader data directly from unmanaged component-level side-effects; consumers MUST use `Route.useLoaderData()` or `useSuspenseQuery()` bound strictly to the route context. ## Bad vs Good Implementations ### Unsynchronized Loader Fetching with Silent In-Flight Preload Races #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The loader ignores the route's abortController signal, allowing cancelled preload requests to continue execution and potentially resolve out of order. Furthermore, the mutation handler does not call router.invalidate(), causing subsequently preloaded routes or parallel segments to display desynchronized stale data. ```typescript import { createFileRoute } from '@tanstack/react-router'; export const Route = createFileRoute('/invoices/$invoiceId')({ // BAD: Ignores abortController, uses unmanaged fetch without preload stale constraints, // and leaves the router vulnerable to stale in-flight preload overwrite races. loader: async ({ params }) => { const res = await fetch(`/api/invoices/${params.invoiceId}`); if (!res.ok) throw new Error('Failed to load invoice'); return res.json(); }, component: InvoiceComponent, }); function InvoiceComponent() { const invoice = Route.useLoaderData(); const handlePay = async () => { await fetch(`/api/invoices/${invoice.id}/pay`, { method: 'POST' }); // BAD: Navigation/re-fetch without router.invalidate() leaves preloaded caches stale }; return <button onClick={handlePay}>Pay Invoice</button>; } ``` #### Production Standard (Correct) > **Standard**: The good example binds the Route's `abortController.signal` directly to the query lifecycle via `ensureQueryData`, ensuring superseded preloads are cancelled immediately. It configures deterministic `preloadStaleTime` and guarantees that the mutation triggers `await router.invalidate()` to sync all active and cached loader states. ```typescript import { createFileRoute, useRouter } from '@tanstack/react-router'; import { queryOptions } from '@tanstack/react-query'; const invoiceQueryOptions = (invoiceId: string) => queryOptions({ queryKey: ['invoices', invoiceId], queryFn: async ({ signal }) => { const res = await fetch(`/api/invoices/${invoiceId}`, { signal }); if (!res.ok) throw new Error('Failed to load invoice'); return res.json(); }, staleTime: 10_000, }); export const Route = createFileRoute('/invoices/$invoiceId')({ preloadStaleTime: 10_000, loader: ({ context: { queryClient }, params, abortController }) => { return queryClient.ensureQueryData({ ...invoiceQueryOptions(params.invoiceId), // Explicitly tie Route abortController signal to prevent in-flight races signal: abortController.signal, }); }, component: InvoiceComponent, }); function InvoiceComponent() { const router = useRouter(); const invoice = Route.useLoaderData(); const handlePay = async () => { await fetch(`/api/invoices/${invoice.id}/pay`, { method: 'POST' }); // Invalidate all route caches synchronously to maintain UI-router cache invariants await router.invalidate(); }; return <button onClick={handlePay}>Pay Invoice</button>; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: TanStack Router Preload Cache Synchronization and Mutation Invalidation Standards

TanStack Router Preload Cache Synchronization and Mutation Invalidation Standards defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic loader cache lifecycles, abort signal propagation, and synchronous route invalidation across rapid client transitions in TanStack Router. Prevents race conditions and stale-data read anomalies caused by asynchronous preloads competing with concurrent mutations or fast navigational switches. 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: Unsynchronized In-Flight Route Preloads Overwriting Fresh Mutation State and Creating Stale Loader Anomalies 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	Unsynchronized In-Flight Route Preloads Overwriting Fresh Mutation State and Creating Stale Loader Anomalies	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 forward the Route loader's `abortController.signal` directly to downstream fetch clients or TanStack Query options to cancel stale in-flight preloads on route transitions.

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.