Vite 6 Environment API Cross-Runtime Shared Memory & Module Graph Isolation

--- description: Vite 6 Environment API Cross-Runtime Shared Memory & Module Graph Isolation - Vite 6 introduces multi-environment orchestration allowing concurrent execution of client, SSR (Node), and edge/workerd runtimes within a unified dev server. This rule enforces strict module execution and heap boundaries between environments, prohibiting cross-runtime in-memory singleton access, cross-environment module graph contamination, and non-serializable IPC payloads. globs: vite.config.{ts,js,mjs}, plugins/**/*.{ts,js}, src/**/*.{ts,tsx}, server/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-environment-api-cross-runtime-isolation" --- # Vite 6 Environment API Cross-Runtime Shared Memory & Module Graph Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Runtime Memory Leakage and Module Graph Contamination via Unscoped Singletons in Vite 6 DevEnvironments ## System Constraints You are a Principal Software Architect enforcing runtime isolation boundaries in Vite 6 Environment API implementations. Vite 6 isolates runtime targets (e.g., Node.js SSR, Cloudflare workerd, browser client) into distinct DevEnvironment instances. You must strictly enforce zero shared mutable heap state, environment-scoped plugin hooks, explicit cross-boundary serialization, and complete separation of module graphs. ## Strict Guidelines - Engineers MUST ALWAYS access runtime module graphs through 'this.environment.moduleGraph' inside Vite plugin hooks, NEVER through the root 'server.moduleGraph'. - Engineers MUST NOT share in-memory mutable singletons, Node.js native streams, or process-bound object references across distinct Vite 6 DevEnvironments. - Code interacting across environment boundaries (such as Node dev-server orchestrating an edge runtime environment) MUST communicate strictly via serializable RPC, Fetch API standards (standard Request/Response), or structured message passing via HotChannel. - Custom Vite plugins MUST verify 'this.environment.name' before applying environment-specific transforms, module resolutions, or injecting runtime polyfills. - Services running in isolated environments (e.g., workerd, web workers) MUST NEVER directly import or invoke modules intended for Node-only environments (e.g., 'node:fs', 'node:child_process') without explicit runtime gating and mock environment separation. ## Bad vs Good Implementations ### Scoped DevEnvironment Plugin Hook & IPC Communication #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The plugin accesses the root 'server.moduleGraph' (which conflates distinct runtime targets), maintains a mutable in-memory cache shared across concurrent environments (Node.js and Workerd), and assumes Node.js globals ('process.env') are universally accessible across all target environments. ```typescript import type { Plugin, ViteDevServer } from 'vite'; // ANTI-PATTERN: Global shared mutable state across environments const crossRuntimeSharedCache = new Map<string, unknown>(); export function leakyCrossRuntimePlugin(): Plugin { let rootServer: ViteDevServer; return { name: 'leaky-cross-runtime', configureServer(server) { rootServer = server; }, async transform(code, id) { // VIOLATION: Using global root server moduleGraph instead of environment-specific graph const mod = rootServer.moduleGraph.getModuleById(id); // VIOLATION: Mutating shared heap memory accessed by both Node SSR and Workerd edge runtimes crossRuntimeSharedCache.set(id, { ast: mod?.transformResult, raw: code }); // VIOLATION: Returning Node-specific process object in code targeting edge environment if (id.includes('entry.edge.ts')) { return `${code}; globalThis.__SERVER_CACHE__ = process.env;`; } return code; }, }; } ``` #### Production Standard (Correct) > **Standard**: The compliant code uses 'this.environment' to scope module resolution and graph operations to the specific execution context. It uses a WeakMap keyed on the DevEnvironment to prevent cross-runtime memory leaks, and cleanly branches logic based on 'this.environment.name' rather than leaking process globals. ```typescript import type { Plugin, EnvironmentModuleNode } from 'vite'; export function isolatedCrossRuntimePlugin(): Plugin { // Invariant: Scoped WeakMaps to avoid cross-environment heap retention const environmentCaches = new WeakMap<object, Map<string, string>>(); return { name: 'isolated-cross-runtime', // Enforce environment-specific transform execution async transform(code: string, id: string) { // INVARIANT 1: Bound to current environment context const currentEnv = this.environment; if (!currentEnv) { return null; } // INVARIANT 2: Access the isolated module graph for this specific environment const envMod: EnvironmentModuleNode | undefined = currentEnv.moduleGraph.getModuleById(id); // INVARIANT 3: Store state keyed per environment instance let cache = environmentCaches.get(currentEnv); if (!cache) { cache = new Map<string, string>(); environmentCaches.set(currentEnv, cache); } cache.set(id, envMod?.id ?? id); // INVARIANT 4: Strict environment boundary check before injecting runtime code if (currentEnv.name === 'edge') { return { code: `// Edge-safe isolated runtime shim\n${code}`, map: null, }; } return null; }, }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Cross-Runtime Shared Memory & Module Graph Isolation

Vite 6 Environment API Cross-Runtime Shared Memory & Module Graph Isolation defines an industrial-grade behavioral standard for frontend engineering. Vite 6 introduces multi-environment orchestration allowing concurrent execution of client, SSR (Node), and edge/workerd runtimes within a unified dev server. This rule enforces strict module execution and heap boundaries between environments, prohibiting cross-runtime in-memory singleton access, cross-environment module graph contamination, and non-serializable IPC payloads. 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 Memory Leakage and Module Graph Contamination via Unscoped Singletons in 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-Runtime Memory Leakage and Module Graph Contamination via Unscoped Singletons in 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 runtime module graphs through 'this.environment.moduleGraph' inside Vite plugin hooks, NEVER through the root '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.