Vite 6 Environment API Server-Client Module Graph Boundary Invariant

--- description: Vite 6 Environment API Server-Client Module Graph Boundary Invariant - Vite 6 introduces the Environment API to provide isolated module graphs for discrete runtimes (e.g., client, ssr, edge workers). Sharing mutable plugin caches, referencing legacy root server.moduleGraph, or failing to isolate module graph traversal across environments causes catastrophic server secret leaks, Node.js runtime leakage into client bundles, and untracked cross-environment memory leaks. globs: vite.config.{ts,js,mjs}, plugins/**/*.{ts,js}, src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-environment-api-module-graph-boundary" --- # Vite 6 Environment API Server-Client Module Graph Boundary Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Plugin Caching and Root ModuleGraph Cross-Contamination Across Vite 6 Environments ## System Constraints You are a Principal Software Architect enforcing the Vite 6 Environment API Module Graph Boundary Invariant. In Vite 6, each environment ('client', 'ssr', 'workerd', etc.) maintains an independent, hermetic ModuleGraph. You must strictly forbid the usage of root `server.moduleGraph`, prohibit cross-environment mutable shared state within plugin closures, mandate environment scoping via `this.environment`, and ensure server-only modules and native bindings are strictly barred from client environments. ## Strict Guidelines - Engineers MUST ALWAYS reference environment-scoped module graphs using `this.environment.moduleGraph` inside plugin hooks instead of the deprecated or client-bound `server.moduleGraph`. - Engineers MUST NEVER maintain global, un-namespaced plugin caches or WeakMaps across Vite plugin hooks without keying them by `this.environment.name` or holding per-environment state within `environment.plugins`. - Code SHOULD explicitly gate transforms, resolve IDs, and virtual module emissions by verifying `this.environment.name` or `this.environment.mode`. - Services MUST prevent server-only modules, Node.js built-ins, and privileged configurations from resolving into non-server environments by throwing deterministic resolution errors during `resolveId`. - Components NEVER import server-only entrypoints, configuration secrets, or environment-agnostic state containers that retain active runtime references across environment boundaries. ## Bad vs Good Implementations ### Vite 6 Environment-Aware Plugin Hook Implementation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The plugin maintains a single process-wide `transformCache` shared across client, SSR, and worker environments, leaking transformed code between runtimes. It attempts to traverse the root `server.moduleGraph` instead of the active `this.environment.moduleGraph`, failing to respect the Vite 6 isolated graph boundary. ```typescript import { type Plugin } from 'vite'; // ANTI-PATTERN: Shared global cache across all Vite 6 environments // Causes memory leaks and cross-runtime graph invalidation corruption const transformCache = new Map<string, string>(); export function brokenModuleBoundaryPlugin(): Plugin { return { name: 'broken-module-boundary', transform(code, id) { // CRITICAL: Implicitly assumes single module graph or client-only context if (transformCache.has(id)) { return transformCache.get(id); } // Leaks server-side module resolution into client graph via root moduleGraph const clientModule = this.meta?.rollupVersion ? null : (this as any).server?.moduleGraph.getModuleById(id); if (clientModule && code.includes('process.env.SECRET_API_KEY')) { // Server secret inadvertently exposed to client module graph return code; } transformCache.set(id, code); return code; }, }; } ``` #### Production Standard (Correct) > **Standard**: The good implementation uses a `WeakMap<DevEnvironment, State>` to strictly isolate cached state to its active execution environment, resolves nodes solely through `this.environment.moduleGraph`, and enforces runtime boundaries by explicitly blocking `.server` modules inside client environments. ```typescript import { type Plugin, type DevEnvironment } from 'vite'; interface EnvironmentTransformState { cache: Map<string, string>; } export function hermeticModuleBoundaryPlugin(): Plugin { // Invariant: Isolate state per environment instance const environmentStates = new WeakMap<DevEnvironment, EnvironmentTransformState>(); function getEnvState(env: DevEnvironment): EnvironmentTransformState { let state = environmentStates.get(env); if (!state) { state = { cache: new Map() }; environmentStates.set(env, state); } return state; } return { name: 'hermetic-module-boundary', resolveId(source) { // Guard against leaking server-only code into client runtime if (this.environment.name === 'client' && source.endsWith('.server')) { throw new Error( `[vite-env-boundary] Module '${source}' cannot be resolved within '${this.environment.name}' environment.` ); } return null; }, transform(code, id) { const env = this.environment as DevEnvironment; const state = getEnvState(env); if (state.cache.has(id)) { return state.cache.get(id); } // Invariant: Always query the scoped environment module graph const mod = env.moduleGraph.getModuleById(id); if (mod && this.environment.name === 'client' && code.includes('process.env.SECRET_API_KEY')) { throw new Error(`[vite-env-boundary] Server credentials detected in client module: ${id}`); } state.cache.set(id, code); return code; }, }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Server-Client Module Graph Boundary Invariant

Vite 6 Environment API Server-Client Module Graph Boundary Invariant defines an industrial-grade behavioral standard for frontend engineering. Vite 6 introduces the Environment API to provide isolated module graphs for discrete runtimes (e.g., client, ssr, edge workers). Sharing mutable plugin caches, referencing legacy root server.moduleGraph, or failing to isolate module graph traversal across environments causes catastrophic server secret leaks, Node.js runtime leakage into client bundles, and untracked cross-environment memory leaks. 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 Plugin Caching and Root ModuleGraph Cross-Contamination Across Vite 6 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 Plugin Caching and Root ModuleGraph Cross-Contamination Across Vite 6 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 reference environment-scoped module graphs using `this.environment.moduleGraph` inside plugin hooks instead of the deprecated or client-bound `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.