Vite 6 Environment API Multi-Runtime Module Execution Isolation

--- description: Vite 6 Environment API Multi-Runtime Module Execution Isolation - Enforces strict runtime module and state isolation across client, SSR Node, and edge worker compilation environments using the Vite 6 Environment API. Prevents cross-environment global state pollution, prototype tampering, and memory leaks by ensuring each runner uses isolated module runners, environment-scoped dev plugins, and runtime-agnostic module evaluation. globs: vite.config.{ts,js,mjs}, src/**/*.{ts,tsx,js,jsx}, server/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-environment-api-runtime-isolation-vite-6-environme-913" --- # Vite 6 Environment API Multi-Runtime Module Execution Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Module Evaluation Sharing and Unscoped State Leakage Across Heterogeneous Vite Environments ## System Constraints You are a Principal Engineer enforcing Vite 6 Environment API Multi-Runtime Module Execution Isolation. Mandate invariants that keep client, server (Node.js), and edge (workerd/wintercg) execution graph states isolated within Vite 6 dev servers and build pipelines. ## Strict Guidelines - Engineers MUST ALWAYS declare runtime environments explicitly using Vite 6 `environments` configuration blocks (e.g., `client`, `ssr`, `edge`) instead of relying on legacy monolithic `ssrLoadModule`. - Engineers MUST NOT access, mutate, or share process globals (such as `process.env`, `globalThis`, or polyfilled `fetch`) across concurrent module runner executions. - Custom Vite plugins MUST use `this.environment` within plugin hooks to scope asset transformations and module resolutions to the target execution runner. - Module runners MUST instantiate dedicated `ModuleRunner` or `createRunnableDevEnvironment` contexts with isolated module evaluators and clearable caches to prevent memory retention across HMR cycles. - Shared runtime utilities MUST NEVER store mutable singletons in file-scope top-level variables across environments; they must be managed via explicit environment dependency injection or context containers. ## Bad vs Good Implementations ### Configuring Vite 6 Isolated Environments vs Legacy Shared SSR Runner #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Relies on legacy monolithic SSR settings and mutates a process-level global across client and worker execution contexts, causing state leakage and incorrect runtime behavior when edge and client modules compile concurrently. ```typescript import { defineConfig } from 'vite'; // ANTI-PATTERN: Vite 5 monolithic SSR configuration attempting to run edge and client code in a single graph export default defineConfig({ ssr: { target: 'webworker', noExternal: true }, plugins: [{ name: 'leak-state-plugin', transform(code, id) { // Mutating shared module state across both client and edge targets (globalThis as any).__SHARED_DEV_CACHE__ = (globalThis as any).__SHARED_DEV_CACHE__ || new Map(); (globalThis as any).__SHARED_DEV_CACHE__.set(id, code); return code; } }] }); ``` #### Production Standard (Correct) > **Standard**: Defines explicit compilation runners via the Vite 6 Environment API, isolating module conditions per target and utilizing `this.environment` in plugin hooks to eliminate cross-runner state pollution. ```typescript import { defineConfig } from 'vite'; // PRODUCTION FIX: Vite 6 Environment API with isolated runtime configurations export default defineConfig({ environments: { client: { build: { outDir: 'dist/client' } }, ssr: { build: { outDir: 'dist/server' } }, edge: { resolve: { conditions: ['worker', 'edge-light', 'workerd'] }, build: { outDir: 'dist/edge' } } }, plugins: [{ name: 'isolated-env-plugin', transform(code, id) { // Scoped execution access per environment runner const env = this.environment; if (env.name === 'edge') { // Edge-specific isolated transform return code; } return code; } }] }); ``` ### Runtime Module Execution via ModuleRunner vs Unscoped ssrLoadModule #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: `ssrLoadModule` loads code directly into the Node.js process global realm, preventing edge polyfill isolation and causing uncontained module cache leaks across requests. ```typescript import { ViteDevServer } from 'vite'; // ANTI-PATTERN: Legacy ssrLoadModule shares Node.js global context and causes prototype contamination export async function handleRequest(server: ViteDevServer, url: string) { // Leaks evaluation cache across mixed edge/server simulated environments const entry = await server.ssrLoadModule('/src/entry-server.ts'); return entry.render(url); } ``` #### Production Standard (Correct) > **Standard**: Uses Vite 6 `ModuleRunner` paired with an isolated runtime evaluator bound strictly to the `edge` environment, ensuring runtime sandboxing and deterministic resource reclamation via `runner.close()`. ```typescript import { createServer } from 'vite'; import { ModuleRunner, ESModulesEvaluator } from 'vite/module-runner'; // PRODUCTION FIX: Vite 6 ModuleRunner with sandboxed runtime evaluator export async function handleRequest(url: string) { const server = await createServer(); const edgeEnvironment = server.environments.edge; // Instantiate an isolated ModuleRunner bound strictly to the edge environment runner const runner = new ModuleRunner( { root: server.config.root, transport: edgeEnvironment.hot }, new ESModulesEvaluator() ); try { const entry = await runner.import('/src/entry-edge.ts'); return await entry.render(url); } finally { await runner.close(); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Multi-Runtime Module Execution Isolation

Vite 6 Environment API Multi-Runtime Module Execution Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict runtime module and state isolation across client, SSR Node, and edge worker compilation environments using the Vite 6 Environment API. Prevents cross-environment global state pollution, prototype tampering, and memory leaks by ensuring each runner uses isolated module runners, environment-scoped dev plugins, and runtime-agnostic module evaluation. 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 Module Evaluation Sharing and Unscoped State Leakage Across Heterogeneous Vite Environments 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 Module Evaluation Sharing and Unscoped State Leakage Across Heterogeneous Vite Environments	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 declare runtime environments explicitly using Vite 6 `environments` configuration blocks (e.g., `client`, `ssr`, `edge`) instead of relying on legacy monolithic `ssrLoadModule`.

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.