Vite 6 Environment API Multi-Runtime SSR Context Isolation Invariant

--- description: Vite 6 Environment API Multi-Runtime SSR Context Isolation Invariant - Enforces strict boundary isolation and module runner sandboxing across concurrent Vite 6 Environment API runtimes (Client, Node.js, and Workerd). Prevents mutable module-scoped singletons, global prototype pollution, and cross-runtime reference leakage during concurrent server-side evaluation. Mandates AsyncLocalStorage-backed context dispatching or explicit environment-scoped dependency injection containers. globs: vite.config.ts, vite.config.*.ts, src/server/**/*.{ts,tsx}, src/entry-server.{ts,tsx}, src/runtimes/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-environment-api-ssr-context-isolation-vite-6-environme-368" --- # Vite 6 Environment API Multi-Runtime SSR Context Isolation Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Runtime Global Pollution and Leaky Module-Level Singletons in Multi-Environment SSR ## System Constraints You are a Principal Engineer enforcing Vite 6 Environment API Multi-Runtime SSR Context Isolation Invariant. Mandate invariants that strictly prevent shared process-level memory, mutable module singletons, and global scope mutations across heterogeneous runtime targets (such as Node.js dev servers hosting client transforms and Cloudflare Workerd runner instances). Ensure all per-request and per-environment states are encapsulated within isolated runtime instances or AsyncLocalStorage contexts. ## Strict Guidelines - Engineers MUST ALWAYS configure distinct `EnvironmentOptions` with isolated `ModuleRunner` instances for each runtime target (e.g., 'client', 'ssr', 'edge') in Vite 6. - Engineers MUST NOT mutate `globalThis`, global prototypes, or shared Node.js process state inside plugins, transform hooks, or runtime entrypoints. - Code SHOULD encapsulate request-specific state and context via `AsyncLocalStorage` or scoped dependency injection rather than module-level top-level variables. - Services MUST ensure that bindings intended for edge environments (e.g., Workerd KV, Durable Objects) never leak into Node.js server runners or browser evaluation trees. - Components NEVER rely on ambient module evaluation order or global flags (`window.__INITIAL_DATA__` or `global.__SSR_CONTEXT__`) for server rendering passes. ## Bad vs Good Implementations ### Anti-Pattern: Leaking Module-Level Singletons & Global State Across SSR Runtimes #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Mutating module-scoped state (`globalRequestContext`) and `globalThis` results in critical race conditions and data leaks across concurrent requests. In Vite 6 multi-environment setups, evaluating modules without explicit Environment API module runners contaminates Node.js and Workerd evaluation contexts. ```typescript // vite.config.ts / server.ts - INCORRECT: Shared module singleton across requests/runtimes import { createServer } from 'vite'; let globalRequestContext: { userId?: string; envName?: string } = {}; export const setSSRContext = (ctx: typeof globalRequestContext) => { globalRequestContext = ctx; }; export async function handleRequest(url: string, runtime: 'node' | 'workerd') { // Leaking state across concurrent runs in the same Node.js host process setSSRContext({ userId: 'usr_123', envName: runtime }); // Poluting global scope directly (globalThis as unknown as { __CURRENT_RUNTIME__: string }).__CURRENT_RUNTIME__ = runtime; const vite = await createServer(); // Legacy Vite SSR loading sharing the default Node.js module graph const { render } = await vite.ssrLoadModule('/src/entry-server.ts'); return render(url, globalRequestContext); } ``` #### Production Standard (Correct) > **Standard**: Leverages Vite 6 `RunnableDevEnvironment` and environment-specific `ModuleRunner` instances. Concurrent execution state is safely managed within `AsyncLocalStorage`, preventing cross-environment module evaluation contamination and avoiding any global object mutations. ```typescript // vite.config.ts / server.ts - CORRECT: Vite 6 Environment API with sandboxed ModuleRunner import { createServer, type RunnableDevEnvironment } from 'vite'; import { AsyncLocalStorage } from 'node:async_hooks'; export interface RequestContext { readonly userId: string; readonly runtimeName: 'client' | 'ssr' | 'workerd'; } export const requestStore = new AsyncLocalStorage<RequestContext>(); export async function handleRequest(url: string, targetRuntime: 'ssr' | 'workerd') { const vite = await createServer(); // Access isolated runtime environment instance via Vite 6 Environment API const environment = vite.environments[targetRuntime] as RunnableDevEnvironment; if (!environment || !('runner' in environment)) { throw new Error(`Environment ${targetRuntime} is not configured as a RunnableDevEnvironment`); } const context: RequestContext = Object.freeze({ userId: 'usr_123', runtimeName: targetRuntime }); return requestStore.run(context, async () => { // Execute entry point inside the sandboxed runner specific to this environment const entryModule = await environment.runner.import('/src/entry-server.ts'); return entryModule.render(url); }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Multi-Runtime SSR Context Isolation Invariant

Vite 6 Environment API Multi-Runtime SSR Context Isolation Invariant defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary isolation and module runner sandboxing across concurrent Vite 6 Environment API runtimes (Client, Node.js, and Workerd). Prevents mutable module-scoped singletons, global prototype pollution, and cross-runtime reference leakage during concurrent server-side evaluation. Mandates AsyncLocalStorage-backed context dispatching or explicit environment-scoped dependency injection containers. 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: Cross-Runtime Global Pollution and Leaky Module-Level Singletons in Multi-Environment SSR 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	Cross-Runtime Global Pollution and Leaky Module-Level Singletons in Multi-Environment SSR	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 distinct `EnvironmentOptions` with isolated `ModuleRunner` instances for each runtime target (e.g., 'client', 'ssr', 'edge') in Vite 6.

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.