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

--- description: Vite 6 Environment API Cross-Runtime Module Graph & Memory Isolation - Mandates strict separation of module evaluation graphs, runtime instances, and HMR boundaries across Client, SSR (Node.js), and Edge environments utilizing Vite 6's Environment API. Prevents cross-runtime state pollution, module graph contamination, and invalid module executions across heterogeneous target runtimes. 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/vite6-environment-api-runtime-isolation-standard" --- # Vite 6 Environment API Cross-Runtime Module Graph & Memory Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Runtime Memory Leakage and Module Graph Contamination via Legacy Unified Server APIs ## System Constraints You are a Principal Software Architect enforcing the Vite 6 Environment API Cross-Runtime Isolation Standard. You must mandate strict physical and logical boundaries between Client, SSR, and Edge runtimes during development, HMR, and build phases. Reject any reliance on deprecated Vite 5 single-module-graph patterns, global execution side-effects, or cross-environment memory bleeding. ## Strict Guidelines - Engineers MUST configure distinct execution runtimes using Vite 6 `environments` definitions (`environments.client`, `environments.ssr`, `environments.edge`) instead of relying on top-level global runtime configurations. - Engineers MUST NOT access or mutate `server.moduleGraph` globally; plugins MUST target `environment.moduleGraph` via the Vite 6 `hotUpdate` hook to guarantee isolation. - Code MUST use the Vite 6 `hotUpdate(this, { modules, environment })` signature instead of legacy `handleHotUpdate(ctx)` when performing fine-grained HMR updates across specific runtime instances. - Services running in isolated environments (e.g., Cloudflare Workers / Edge / Node SSR) MUST be executed using `environment.runner` (e.g., `ModuleRunner`) rather than legacy `server.ssrLoadModule`. - Plugins MUST explicitly declare environment constraints (`applyToEnvironment(environment): boolean` or plugin hook environment filtering) to avoid executing runtime-incompatible AST transforms on cross-target module graphs. - Shared utilities NEVER rely on mutable module-level state across boundaries; state bridging between client and server runtimes MUST be orchestrated via serialized IPC or context objects, not shared in-memory singletons. ## Bad vs Good Implementations ### Module Invalidation and HMR Scoping in Custom Plugin #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Legacy `handleHotUpdate` uses `ctx.server.moduleGraph`, which is ambiguous in multi-runtime architectures. It forces identical invalidation semantics across Node, Client, and Edge targets, triggering false-positive invalidations and leaking environment-specific graph state. ```typescript import type { Plugin } from 'vite'; export function brokenHotUpdatePlugin(): Plugin { return { name: 'broken-cross-runtime-plugin', // Anti-pattern: Deprecated handleHotUpdate inspecting global server.moduleGraph handleHotUpdate(ctx) { // Globally invalidates modules across ALL runtimes simultaneously, // causing edge/ssr runtime module mismatch and node-specific leaks into client. const clientModule = ctx.server.moduleGraph.getModuleById(ctx.file); if (clientModule) { ctx.server.moduleGraph.invalidateModule(clientModule); } // Indiscriminately returning modules to default HMR engine return ctx.modules; } }; } ``` #### Production Standard (Correct) > **Standard**: Vite 6's `hotUpdate` hook scopes operations directly to `environment.moduleGraph`. Module invalidation and hot event emission occur only within the runtime that owns that specific module instance, preserving isolation. ```typescript import type { Plugin, EnvironmentModuleNode } from 'vite'; export function isolatedHotUpdatePlugin(): Plugin { return { name: 'isolated-cross-runtime-plugin', // Vite 6 standard: Scope HMR processing to the triggering runtime environment hotUpdate: { order: 'pre', handler({ modules, environment }) { // Invariant: Target only the module graph of the active environment const affected: EnvironmentModuleNode[] = []; for (const mod of modules) { const envModule = environment.moduleGraph.getModuleById(mod.id!); if (envModule) { environment.moduleGraph.invalidateModule(envModule); affected.push(envModule); } } // Edge runtime and SSR runtimes handle invalidations independently if (environment.name === 'edge' || environment.name === 'ssr') { environment.hot.send({ type: 'custom', event: 'runtime:invalidate', data: { ids: affected.map(m => m.id) } }); return []; } return affected; } } }; } ``` ### Multi-Runtime Server Architecture Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to isolate multiple target environments (e.g., Browser client vs. Cloudflare Edge vs. Node SSR). Modern architectures containing mixed runtimes collapse into a single target definition, leading to bundling of Node globals into edge workers or browser bundles. ```typescript import { defineConfig } from 'vite'; // Anti-pattern: Monolithic config relying on Vite 5 SSR flags export default defineConfig({ ssr: { noExternal: ['shared-lib'], target: 'node' }, build: { ssr: 'src/entry-server.ts' } }); ``` #### Production Standard (Correct) > **Standard**: Configures granular environments under Vite 6's Environment API, establishing disjoint module resolution conditions, build outputs, and decoupled consumers for Client, Node SSR, and Edge runtimes. ```typescript import { defineConfig } from 'vite'; // Vite 6 Standard: Explicit cross-runtime environment segregation export default defineConfig({ environments: { client: { consumer: 'client', build: { outDir: 'dist/client', rollupOptions: { input: 'src/entry-client.ts' } } }, ssr: { consumer: 'server', resolve: { conditions: ['node', 'import'] }, build: { outDir: 'dist/server', rollupOptions: { input: 'src/entry-server.ts' } } }, edge: { consumer: 'server', resolve: { conditions: ['worker', 'edge-routine', 'import'], noExternal: true }, build: { outDir: 'dist/edge', rollupOptions: { input: 'src/entry-edge.ts' } } } } }); ```

Architectural Specification & Invariant Rationale

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

Vite 6 Environment API Cross-Runtime Module Graph & Memory Isolation defines an industrial-grade behavioral standard for frontend engineering. Mandates strict separation of module evaluation graphs, runtime instances, and HMR boundaries across Client, SSR (Node.js), and Edge environments utilizing Vite 6's Environment API. Prevents cross-runtime state pollution, module graph contamination, and invalid module executions across heterogeneous target runtimes. 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 Legacy Unified Server APIs 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 Legacy Unified Server APIs	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 configure distinct execution runtimes using Vite 6 `environments` definitions (`environments.client`, `environments.ssr`, `environments.edge`) instead of relying on top-level global runtime configurations.

Engineers MUST configure distinct execution runtimes using Vite 6 `environments` definitions (`environments.client`, `environments.ssr`, `environments.edge`) instead of relying on top-level global runtime configurations.

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.