Vite 6 Environment API Multi-Runtime Module Graph & Context Isolation

--- description: Vite 6 Environment API Multi-Runtime Module Graph & Context Isolation - Enforces strict isolation across Vite 6 execution environments (browser, Node.js SSR, and Edge runtimes) using the Environment API. Guarantees zero cross-contamination of module instances, transform caches, and environment variables across heterogeneous execution targets during universal development and bundling. globs: vite.config.ts, vite.config.*.ts, plugins/**/*.ts, src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-environment-api-graph-isolation" --- # Vite 6 Environment API Multi-Runtime Module Graph & Context Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Monolithic Module Graph Querying and Cross-Environment Plugin Cache Leakage ## System Constraints You are a Principal Software Architect enforcing Vite 6 Environment API standards. Mandate strict module graph isolation, runtime-targeted resolve conditions, and isolated plugin states across client, Node.js SSR, and edge environments. Strictly reject legacy Vite dual-graph assumptions (server.moduleGraph) and forbid shared mutable transform state across runtimes. ## Strict Guidelines - Engineers MUST ALWAYS reference `this.environment.moduleGraph` inside plugin hooks instead of the legacy top-level `server.moduleGraph`. - Engineers MUST NOT maintain shared mutable module caches or state across different environments inside plugin scopes; use environment-scoped Maps keyed by `this.environment.name`. - Configurations MUST define discrete `resolve.conditions` per runtime environment (e.g., `['edge-light', 'workerd']` for edge, `['node']` for SSR, `['browser']` for client). - Plugins targeting specific runtimes MUST use the `applyToEnvironment(environment)` hook filter or inspect `this.environment.name` to avoid invalid transformations across mismatched runtimes. - Engineers MUST configure distinct `define` and `envPrefix` namespaces per environment configuration to prevent leaking server-only secret variables into client-side asset graphs. ## Bad vs Good Implementations ### Vite 6 Multi-Environment Configuration and Environment-Aware Plugin #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The plugin shares a single transformCache across all runtimes, leaking server-only secrets into client bundles. Additionally, using server.moduleGraph breaks Vite 6 multi-runtime isolation because it defaults to the client graph rather than querying the specific environment (edge, ssr, or client) executing the code. ```typescript import { defineConfig, type Plugin } from 'vite'; // Anti-pattern: Shared state across all environments and legacy moduleGraph access const transformCache = new Map<string, string>(); export function leakyPlugin(): Plugin { return { name: 'leaky-virtual-plugin', configureServer(server) { server.middlewares.use((req, res, next) => { // Defect: Accesses global client/legacy graph; breaks in multi-runtime edge/SSR const mod = server.moduleGraph.getModuleById('/src/runtime-entry.ts'); next(); }); }, transform(code, id) { // Defect: Shared cache pollutes across client, node, and edge builds if (transformCache.has(id)) return transformCache.get(id); const result = code.replace(/__API_SECRET__/g, process.env.API_SECRET || ''); transformCache.set(id, result); return result; } }; } export default defineConfig({ plugins: [leakyPlugin()] }); ``` #### Production Standard (Correct) > **Standard**: Adheres to the Vite 6 Environment API by declaring discrete environments ('client', 'ssr', 'edge') with custom resolve conditions, referencing runtime nodes via `this.environment.moduleGraph`, and partitioning plugin caches by `this.environment.name` to prevent cross-runtime data leaks. ```typescript import { defineConfig, type Plugin } from 'vite'; interface EnvironmentScopedState { cache: Map<string, string>; } export function isolatedMultiRuntimePlugin(): Plugin { const envStores = new Map<string, EnvironmentScopedState>(); function getStore(envName: string): EnvironmentScopedState { let store = envStores.get(envName); if (!store) { store = { cache: new Map() }; envStores.set(envName, store); } return store; } return { name: 'isolated-multi-runtime-plugin', transform(code, id) { // Invariant: Isolate module transform and state per runtime environment const currentEnv = this.environment.name; const store = getStore(currentEnv); if (store.cache.has(id)) { return { code: store.cache.get(id)! }; } // Invariant: Never inject secrets into client-targeted environment graphs let transformed = code; if (this.environment.name === 'ssr' || this.environment.name === 'edge') { transformed = code.replace(/__RUNTIME_TARGET__/g, currentEnv); } else { transformed = code.replace(/__RUNTIME_TARGET__/g, 'client'); } // Query the specific runtime environment module graph const currentModuleNode = this.environment.moduleGraph.getModuleById(id); if (currentModuleNode) { store.cache.set(id, transformed); } return { code: transformed }; } }; } export default defineConfig({ plugins: [isolatedMultiRuntimePlugin()], environments: { client: { build: { outDir: 'dist/client' }, resolve: { conditions: ['browser'] } }, ssr: { build: { outDir: 'dist/ssr' }, resolve: { conditions: ['node', 'import'] } }, edge: { build: { outDir: 'dist/edge' }, resolve: { conditions: ['edge-light', 'workerd', 'worker'] } } } }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Multi-Runtime Module Graph & Context Isolation

Vite 6 Environment API Multi-Runtime Module Graph & Context Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation across Vite 6 execution environments (browser, Node.js SSR, and Edge runtimes) using the Environment API. Guarantees zero cross-contamination of module instances, transform caches, and environment variables across heterogeneous execution targets during universal development and bundling. 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: Monolithic Module Graph Querying and Cross-Environment Plugin Cache Leakage 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	Monolithic Module Graph Querying and Cross-Environment Plugin Cache Leakage	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 `this.environment.moduleGraph` inside plugin hooks instead of the legacy top-level `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.