TanStack Start Streaming Loader Request-Scoped Context Isolation

--- description: TanStack Start Streaming Loader Request-Scoped Context Isolation - Enforces strict request-scoped context isolation during TanStack Start deferred SSR streaming. Prevents cross-tenant state pollution, leaked server-side caches, and async context interleaving when resolving deferred loader promises across concurrent HTTP chunks. globs: app/**/*.{ts,tsx}, src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tanstack-start-streaming-loader-context-isolation-guardrail" --- # TanStack Start Streaming Loader Request-Scoped Context Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Module-Level Shared State and Unscoped Singletons in Deferred Streaming Loaders ## System Constraints You are a Principal Engineer enforcing TanStack Start Streaming Loader Context-Isolation Guardrails. Mandate that all loaders, deferred streaming chunks, and server functions extract tenancy and authentication context strictly from request-bound dependency injection, AsyncLocalStorage, or TanStack Start router context. Prohibit module-level shared memory, global mutation, and cross-request state leakage during asynchronous chunk streaming. ## Strict Guidelines - Engineers MUST ALWAYS pass request context through TanStack Router's `context` factory or AsyncLocalStorage when initiating deferred streaming loader promises. - Engineers MUST NOT cache tenant-specific state, authentication tokens, or query clients in module-scoped global variables across streaming SSR chunks. - Loaders utilizing `defer()` MUST capture execution context by value at chunk invocation time to prevent async interleaving from binding to a subsequent request's lifecycle. - QueryClient and server store instances MUST be instantiated per-request inside the router `createRouter` context and disposed of when the HTTP stream terminates. - Components rendering deferred chunks via `Await` NEVER read tenant identifiers or authorization credentials from global fallback singletons. ## Bad vs Good Implementations ### Module-Level State vs Request-Scoped Context in Deferred Streaming Loaders #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The loader relies on a module-level variable `cachedTenantId`. Because deferred promises resolve asynchronously while the HTTP response streams, subsequent concurrent requests overwrite this global variable, causing Cross-Tenant Data Leaks where Tenant B sees Tenant A's private dashboard data. ```typescript import { createFileRoute, defer } from '@tanstack/react-router'; import { fetchTenantDashboard } from '~/server/tenant'; // CRITICAL FLAW: Module-scoped variable shared across concurrent SSR requests let cachedTenantId: string | null = null; export const Route = createFileRoute('/dashboard')({ loader: async ({ context, location }) => { // Pollutes global memory across streaming requests cachedTenantId = (context as { tenantId: string }).tenantId; const deferredData = defer( new Promise(async (resolve) => { // By the time this deferred chunk resolves, cachedTenantId may have // been overwritten by another concurrent tenant's incoming request! await new Promise((r) => setTimeout(r, 200)); const data = await fetchTenantDashboard(cachedTenantId!); resolve(data); }) ); return { deferredData }; }, }); ``` #### Production Standard (Correct) > **Standard**: Tenant context is immutably extracted from the request-scoped router context and enclosed within the deferred promise. No module-level state is modified, ensuring thread-safe concurrency and complete tenant isolation across streaming SSR responses. ```typescript import { createFileRoute, defer } from '@tanstack/react-router'; import { fetchTenantDashboard } from '~/server/tenant'; interface RouterContext { tenantId: string; requestId: string; } export const Route = createFileRoute('/dashboard')({ loader: ({ context }: { context: RouterContext }) => { // Capture tenantId by lexical scope per request invocation const { tenantId, requestId } = context; // Invariant: Deferred promise encapsulates strictly isolated closure const deferredData = defer( fetchTenantDashboard(tenantId).catch((error: unknown) => { console.error(`Stream error for request ${requestId}:`, error); throw error; }) ); return { tenantId, deferredData, }; }, }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: TanStack Start Streaming Loader Request-Scoped Context Isolation

TanStack Start Streaming Loader Request-Scoped Context Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict request-scoped context isolation during TanStack Start deferred SSR streaming. Prevents cross-tenant state pollution, leaked server-side caches, and async context interleaving when resolving deferred loader promises across concurrent HTTP chunks. 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: Module-Level Shared State and Unscoped Singletons in Deferred Streaming Loaders 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	Module-Level Shared State and Unscoped Singletons in Deferred Streaming Loaders	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 pass request context through TanStack Router's `context` factory or AsyncLocalStorage when initiating deferred streaming loader promises.

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.