TanStack Router Dynamic Preload Rate & Memory Budget Guardrail

--- description: TanStack Router Dynamic Preload Rate & Memory Budget Guardrail - Enforces adaptive, connection-aware, and LRU-capped route preloading within TanStack Router applications. Prevents browser main-thread jank, client-side memory blowup, and mobile cellular data exhaustion by wrapping default route preloading hooks with Save-Data awareness, concurrency throttling, and type-safe cache eviction budgets. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tanstack-router-preload-quota-guardrail" --- # TanStack Router Dynamic Preload Rate & Memory Budget Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unbounded Link Preloading Under High Route Tree Complexity Leading to Network Thrashing and Out-of-Memory Crashes ## System Constraints You are a Principal Frontend Architect enforcing strict memory and network budget invariants for TanStack Router in large enterprise SPAs. You must ensure that intent-based link hovering (preload='intent') does not execute unconstrained network requests or retain unbounded route cache states in client memory, especially across constrained network interfaces (2G/3G/Save-Data). ## Strict Guidelines - Engineers MUST ALWAYS configure `defaultPreload: 'intent'` alongside a dynamic preload predicate that evaluates `navigator.connection.saveData` and effective network connection type (`effectiveType === '4g'`). - Engineers MUST NOT leave `defaultPreloadMaxAge` unbounded; every preloaded route loader MUST define a bounded time-to-live (`preloadStaleTime` / `preloadGcTime`) to prevent leakages across large tree walks. - Custom prefetch utilities MUST enforce a token-bucket or LRU eviction queue capped at a maximum of 10 concurrent prefetch promises to prevent mobile socket pool starvation. - Components MUST NEVER bypass router-level type-safe preloading by manually firing raw query client prefetch queries inside native `onMouseEnter` handlers. - Route definitions MUST explicitly set `preload: false` on heavyweight leaf modules (such as canvas renderers, report exporters, or complex data grids) to isolate expensive code bundles from hovering cascades. ## Bad vs Good Implementations ### Configuring Adaptive Preload Quota in TanStack Router Instance #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Defaulting to an aggressive 50ms intent preload with unbounded TTL and zero network-condition checks exhausts cellular bandwidth and rapidly blows up the client JS heap when hovering across dense navigation menus. ```typescript import { createRouter } from '@tanstack/react-router'; import { routeTree } from './routeTree.gen'; // ANTI-PATTERN: Unbounded intent prefetching blindly triggers chunk and loader downloads // regardless of cellular data plans, low-end device CPU, or active memory pressure. export const router = createRouter({ routeTree, defaultPreload: 'intent', defaultPreloadDelay: 50, }); ``` #### Production Standard (Correct) > **Standard**: Inspects Client Network API hints, raises hover latency threshold to 250ms to filter out spurious cursor sweeps, and enforces strict 60s GC limits on prefetched route data. ```typescript import { createRouter } from '@tanstack/react-router'; import { routeTree } from './routeTree.gen'; interface NetworkInformation extends EventTarget { readonly saveData?: boolean; readonly effectiveType?: 'slow-2g' | '2g' | '3g' | '4g'; } function canPreloadUnderBudget(): boolean { if (typeof window === 'undefined') return false; const nav = navigator as Navigator & { connection?: NetworkInformation }; if (nav.connection?.saveData) return false; if (nav.connection?.effectiveType && nav.connection.effectiveType !== '4g') return false; return true; } export const router = createRouter({ routeTree, defaultPreload: canPreloadUnderBudget() ? 'intent' : false, defaultPreloadDelay: 250, defaultPreloadStaleTime: 30_000, // 30s max cache for intent preload defaultPreloadGcTime: 60_000, // Hard GC bound after 1 minute context: { canPreload: canPreloadUnderBudget, }, }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: TanStack Router Dynamic Preload Rate & Memory Budget Guardrail

TanStack Router Dynamic Preload Rate & Memory Budget Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces adaptive, connection-aware, and LRU-capped route preloading within TanStack Router applications. Prevents browser main-thread jank, client-side memory blowup, and mobile cellular data exhaustion by wrapping default route preloading hooks with Save-Data awareness, concurrency throttling, and type-safe cache eviction budgets. 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: Unbounded Link Preloading Under High Route Tree Complexity Leading to Network Thrashing and Out-of-Memory Crashes 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	Unbounded Link Preloading Under High Route Tree Complexity Leading to Network Thrashing and Out-of-Memory Crashes	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 configure `defaultPreload

Engineers MUST ALWAYS configure `defaultPreload: 'intent'` alongside a dynamic preload predicate that evaluates `navigator.connection.saveData` and effective network connection type (`effectiveType === '4g'`).

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.