Vite 6 Runtime Environment API Context Quarantine & Multi-Runtime Isolation

--- description: Vite 6 Runtime Environment API Context Quarantine & Multi-Runtime Isolation - Enforces complete execution isolation and zero global state pollution across concurrent SSR, Edge worker, and client runtimes using the Vite 6 Environment API. Mandates explicit DevEnvironment bindings, ModuleRunner abstraction, and AsyncLocalStorage context encapsulation over global namespace patching. globs: vite.config.{ts,js,mjs}, src/**/*.{ts,tsx}, server/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-runtime-environment-api-context-quarantine" --- # Vite 6 Runtime Environment API Context Quarantine & Multi-Runtime Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Scope Mutation and Cross-Runtime Leaks via Legacy ssrLoadModule and Shared Singletons ## System Constraints You are a Principal Software Architect enforcing strict runtime quarantine using Vite 6's Environment API. You must eradicate ambient global variable mutations (e.g., globalThis.__CONTEXT__), deprecated server.ssrLoadModule anti-patterns, and unisolated module runners. Ensure all multi-environment execution targets (SSR, WebWorker, Workerd, Client) declare explicit DevEnvironment boundary configs, execute through dedicated ModuleRunner instances, and rely on AsyncLocalStorage for per-request isolation. ## Strict Guidelines - Engineers MUST ALWAYS migrate legacy server.ssrLoadModule invocations to server.environments[envName] and vite-runtime ModuleRunner APIs. - Engineers MUST NOT mutate the ambient globalThis, window, or process objects to store request-scoped data, tenant states, or runtime configurations. - Code MUST isolate per-request SSR contextual execution using Node.js or Web-standard AsyncLocalStorage rather than module-level singleton state. - Services MUST configure distinct environment boundaries in vite.config.ts under the environments block (e.g., environments.ssr, environments.workerd, environments.client) with tailored resolve, define, and externalization rules. - Components NEVER assume module-level top-level variables are garbage-collected or reset between concurrent SSR render passes within the same long-running process. - Module runners MUST instantiate ESModulesEvaluator with custom module runner transports when bridging between decoupled Vite DevServer contexts and runtime targets. ## Bad vs Good Implementations ### Vite 6 Server Request Isolation: Deprecated Global Mutation vs Scoped ModuleRunner with AsyncLocalStorage #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Mutating globalThis to store request-scoped metadata causes race conditions and data leaks across concurrent requests. Calling deprecated server.ssrLoadModule avoids Vite 6's Environment API, failing to isolate module graphs across independent targets. ```typescript import { createServer, ViteDevServer } from 'vite'; import type { Request, Response } from 'express'; // ANTI-PATTERN: Shared global state and deprecated Vite 5 ssrLoadModule export async function handleRequest(server: ViteDevServer, req: Request, res: Response): Promise<void> { // Leaking request context onto the global Node.js runtime (globalThis as unknown as { currentRequest: Request }).currentRequest = req; // Deprecated unquarantined SSR loader that shares global evaluation graph const { render } = await server.ssrLoadModule('/src/entry-server.tsx'); const html = await render(req.url); res.status(200).set({ 'Content-Type': 'text/html' }).end(html); } ``` #### Production Standard (Correct) > **Standard**: Leverages Vite 6's Environment API (server.environments.ssr and createServerModuleRunner) to isolate the module execution context, and encapsulates request-bound states strictly inside AsyncLocalStorage to prevent cross-request contamination. ```typescript import { createServer, ViteDevServer } from 'vite'; import { createServerModuleRunner } from 'vite/module-runner'; import { AsyncLocalStorage } from 'node:async_hooks'; import type { Request, Response } from 'express'; interface RequestContext { readonly req: Request; readonly url: string; } export const requestContextStorage = new AsyncLocalStorage<RequestContext>(); export async function handleRequest(server: ViteDevServer, req: Request, res: Response): Promise<void> { // Vite 6: Explicitly target the quarantined SSR DevEnvironment const ssrEnvironment = server.environments.ssr; if (!ssrEnvironment) { throw new Error('SSR environment not configured in Vite server'); } // Instantiate or retrieve dedicated Environment ModuleRunner const runner = createServerModuleRunner(ssrEnvironment); const context: RequestContext = Object.freeze({ req, url: req.url }); // Execute render within quarantined AsyncLocalStorage context await requestContextStorage.run(context, async () => { const entry = await runner.import('/src/entry-server.tsx') as { render: (url: string) => Promise<string>; }; const html = await entry.render(context.url); res.status(200).set({ 'Content-Type': 'text/html' }).end(html); }); } ``` ### Vite 6 Configuration: Quarantined Multi-Environment Boundaries #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Collapsing client, SSR, and edge worker configurations into top-level flags leaks environmental definitions and prevents proper tree-shaking, symbol isolation, and separate runtime polyfills. ```typescript import { defineConfig } from 'vite'; // ANTI-PATTERN: Unified configuration without explicit runtime environment separation export default defineConfig({ ssr: { noExternal: ['lodash-es'], }, define: { // Ambient variable injected globally into both client and SSR contexts __API_HOST__: JSON.stringify(process.env.API_HOST), }, }); ``` #### Production Standard (Correct) > **Standard**: Defines explicit environmental boundaries via Vite 6's `environments` block. Scopes compile-time defines, build artifacts, and module resolution conditions distinctly between client and SSR contexts. ```typescript import { defineConfig } from 'vite'; // Vite 6 Quarantined Environment Definition export default defineConfig({ environments: { client: { build: { outDir: 'dist/client', }, define: { __TARGET_ENV__: JSON.stringify('browser'), }, }, ssr: { build: { outDir: 'dist/server', }, resolve: { noExternal: true, conditions: ['node', 'import'], }, define: { __TARGET_ENV__: JSON.stringify('node-ssr'), }, }, }, }); ```

Architectural Specification & Invariant Rationale

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

Vite 6 Runtime Environment API Context Quarantine & Multi-Runtime Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces complete execution isolation and zero global state pollution across concurrent SSR, Edge worker, and client runtimes using the Vite 6 Environment API. Mandates explicit DevEnvironment bindings, ModuleRunner abstraction, and AsyncLocalStorage context encapsulation over global namespace patching. 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: Global Scope Mutation and Cross-Runtime Leaks via Legacy ssrLoadModule and Shared Singletons 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	Global Scope Mutation and Cross-Runtime Leaks via Legacy ssrLoadModule and Shared Singletons	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 migrate legacy server.ssrLoadModule invocations to server.environments[envName] and vite-runtime ModuleRunner APIs.

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.