Vite 6 Environment API Cross-Runtime State Isolation & HMR Invariant

--- description: Vite 6 Environment API Cross-Runtime State Isolation & HMR Invariant - Enforces strict process, context, and module graph isolation across heterogeneous SSR runtimes (Workerd, Bun, Node) within the Vite 6 Environment API. Prevents shared memory corruption, cross-runtime prototype pollution, and out-of-order state leakage during Hot Module Replacement (HMR). globs: vite.config.ts, vite.config.*.ts, plugins/**/*.ts, src/**/*.server.ts, src/**/*.edge.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-environment-api-runtime-isolation-guardrail" --- # Vite 6 Environment API Cross-Runtime State Isolation & HMR Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Pollinating Global State and Unified Module Graphs Across Heterogeneous Vite 6 DevEnvironments ## System Constraints You are a Principal Software Architect enforcing runtime isolation in Vite 6 multi-environment architectures. You must prevent leakage across heterogeneous runtimes (Node.js, Cloudflare Workerd, Bun) during development and HMR. Mandate isolated module graphs, runtime-specific runners, and environment-scoped communication channels. ## Strict Guidelines - Engineers MUST ALWAYS access the environment-specific module graph via `environment.moduleGraph` instead of the legacy deprecated `server.moduleGraph`. - Engineers MUST NOT execute cross-runtime module evaluation using `server.ssrLoadModule`; they MUST use the dedicated runtime runner `environment.runner.executeId()` or runtime communication transport. - Engineers MUST NEVER mutate host-level `globalThis` or process attributes across edge worker environments (e.g., Workerd) and Node SSR environments. - Vite plugins targeting specific runtime contexts MUST verify `this.environment.name` in transform and build hooks before applying environment-specific AST modifications. - HMR events MUST be routed strictly through `environment.hot.send()` rather than the broadcast `server.hot.send()` to prevent sending non-serializable payload bridges across heterogeneous threads. ## Bad vs Good Implementations ### Module Execution & Module Graph Isolation in Vite 6 Dev Server #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using `server.ssrLoadModule` forces the edge code to execute inside the Node process, bypassing Workerd/miniflare isolates. Accessing `server.moduleGraph` conflates edge and SSR client transforms, while `globalThis` mutation pollutes the host environment. ```typescript import { type ViteDevServer, type Plugin } from 'vite'; export function brokenMultiRuntimePlugin(): Plugin { return { name: 'broken-multi-runtime-plugin', configureServer(server: ViteDevServer) { server.middlewares.use(async (req, res, next) => { if (req.url === '/render-edge') { // VIOLATION: Using deprecated ssrLoadModule executes code in host Node.js // runtime instead of the configured Workerd edge runtime environment. const entry = await server.ssrLoadModule('/src/entry.edge.ts'); // VIOLATION: Cross-pollinating globalThis across edge and host environments globalThis.__SSR_CONTEXT__ = { req, runtime: 'edge' }; // VIOLATION: Accessing unpartitioned root moduleGraph leaks graph states const mod = server.moduleGraph.getModuleById('/src/entry.edge.ts'); server.hot.send({ type: 'custom', event: 'edge-hmr', data: { mod } }); const result = await entry.render(); res.end(result); } }); } }; } ``` #### Production Standard (Correct) > **Standard**: Explicitly retrieves `server.environments.edge`, executes the module strictly within that runtime's isolated execution boundary (`edgeEnv.runner.executeId`), scopes module graph access to `edgeEnv.moduleGraph`, and safely scopes HMR communication via `edgeEnv.hot`. ```typescript import { type ViteDevServer, type Plugin, type DevEnvironment } from 'vite'; export function isolatedMultiRuntimePlugin(): Plugin { return { name: 'isolated-multi-runtime-plugin', configureServer(server: ViteDevServer) { server.middlewares.use(async (req, res, next) => { if (req.url === '/render-edge') { // COMPLIANT: Resolve the explicitly isolated edge environment (e.g., Workerd) const edgeEnv = server.environments.edge as DevEnvironment; if (!edgeEnv) { return next(new Error('Edge environment is not configured')); } // COMPLIANT: Execute entry in isolated runtime via environment runner const entry = await edgeEnv.runner.executeId('/src/entry.edge.ts'); // COMPLIANT: Use environment-scoped moduleGraph and isolated HMR channel const mod = edgeEnv.moduleGraph.getModuleById('/src/entry.edge.ts'); edgeEnv.hot.send('edge:update', { id: mod?.id }); // COMPLIANT: Pass isolated execution context directly via runtime arguments const result = await entry.render({ url: req.url }); res.end(result); } else { next(); } }); } }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Cross-Runtime State Isolation & HMR Invariant

Vite 6 Environment API Cross-Runtime State Isolation & HMR Invariant defines an industrial-grade behavioral standard for frontend engineering. Enforces strict process, context, and module graph isolation across heterogeneous SSR runtimes (Workerd, Bun, Node) within the Vite 6 Environment API. Prevents shared memory corruption, cross-runtime prototype pollution, and out-of-order state leakage during Hot Module Replacement (HMR). 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-Pollinating Global State and Unified Module Graphs Across Heterogeneous Vite 6 DevEnvironments 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-Pollinating Global State and Unified Module Graphs Across Heterogeneous Vite 6 DevEnvironments	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 access the environment-specific module graph via `environment.moduleGraph` instead of the legacy deprecated `server.moduleGraph`.

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.