Vite 6 Environment API Multi-Runtime State Partitioning & Module Graph Isolation

--- description: Vite 6 Environment API Multi-Runtime State Partitioning & Module Graph Isolation - Enforces strict isolation of module graphs, transform pipelines, and memory spaces between Edge (WinterCG) and Node.js SSR runtimes during concurrent compilation under Vite 6. Prevents cross-runtime symbol contamination, shared plugin closure state leaks, and invalid platform polyfill resolution in unified micro-frontend monorepos. globs: **/vite.config.{ts,js,mjs}, **/plugins/**/*.{ts,js,mjs}, src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-environment-api-multi-runtime-isolation-vite-6-environme-269" --- # Vite 6 Environment API Multi-Runtime State Partitioning & Module Graph Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Plugin State Sharing and Cross-Runtime Module Graph Pollution in Concurrent Environments ## System Constraints You are a Principal Software Architect enforcing Vite 6 Environment API Multi-Runtime State Partitioning. You must mandate strict memory, module graph, and configuration boundaries between heterogeneous runtime targets (e.g., Node.js SSR and Edge worker runtimes) during concurrent Vite 6 compilation runs. ## Strict Guidelines - Engineers MUST ALWAYS isolate runtime target definitions under explicit `environments.<name>` configuration records, designating dedicated `resolve.conditions` and `consumer` profiles per runtime. - Engineers MUST NOT store build-step or transform-cache state in module-scoped plugin closures; state MUST be scoped to the active execution context via `this.environment` or an `EnvironmentPluginContainer` map. - Plugins targeting heterogeneous runtimes MUST implement the `applyToEnvironment(environment)` lifecycle hook to filter execution, or explicitly branch execution paths on `this.environment.name` inside generic hooks. - Code destined for Edge (WinterCG/workerd) environments MUST NEVER resolve or alias Node.js built-in modules (`node:fs`, `node:path`, `node:async_hooks`) through inherited root-level SSR resolver aliases. - Services MUST compile independent bundle artifacts per environment using Vite 6's multi-environment build APIs (`builder.buildApp` or separate `builder.build(environment)`) without sharing transformed AST or module nodes across environment module graphs. - Components and shared micro-frontend libraries NEVER access environment-specific runtime primitives directly without polymorphic dependency injection or conditional export mapping across runtime boundaries. ## Bad vs Good Implementations ### Configuring Vite 6 Isolated Multi-Runtime Environments with Environment API #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The legacy configuration shares a single SSR definition, causing Node.js externals and resolution conditions to bleed into Edge targets. Furthermore, the plugin uses a shared top-level `transformCache` closure that cross-contaminates compiled code between concurrent Edge and Node.js execution environments. ```typescript // vite.config.ts - Leaks Node SSR configuration into Edge runtime via shared root scope import { defineConfig } from 'vite'; // ANTI-PATTERN: Shared closure state across environments const transformCache = new Map<string, string>(); export default defineConfig({ ssr: { // Single SSR configuration erroneously shared between Node.js and Edge workers target: 'node', noExternal: true, }, plugins: [ { name: 'leaky-micro-frontend-plugin', transform(code, id) { // Pollutes cache across both runtime targets without environment isolation if (transformCache.has(id)) return transformCache.get(id); const transformed = code.replace('__RUNTIME__', JSON.stringify(process.env.RUNTIME)); transformCache.set(id, transformed); return transformed; } } ] }); ``` #### Production Standard (Correct) > **Standard**: Uses Vite 6's `environments` block to partition compilation pipelines between Node.js and Edge with dedicated resolution conditions. The plugin relies on `applyToEnvironment` and binds state per-runtime using a `WeakMap<Environment, State>`, guaranteeing zero cross-runtime memory leaks or cache collisions. ```typescript // vite.config.ts - Vite 6 Environment API with strict multi-runtime state partitioning import { defineConfig, type Plugin, type Environment } from 'vite'; interface IsolatedEnvironmentCache { cache: Map<string, string>; } function isolatedEnvironmentPlugin(): Plugin { // Partition cache storage per environment instance const environmentStates = new WeakMap<Environment, IsolatedEnvironmentCache>(); return { name: 'isolated-micro-frontend-plugin', applyToEnvironment(env) { // Explicitly allow plugin only in SSR runtimes, isolating from client return env.name === 'edge' || env.name === 'node'; }, buildStart() { environmentStates.set(this.environment, { cache: new Map() }); }, transform(code, id) { const envState = environmentStates.get(this.environment); if (envState?.cache.has(id)) { return envState.cache.get(id); } const runtimeName = this.environment.name; const transformed = code.replace('__RUNTIME__', JSON.stringify(runtimeName)); envState?.cache.set(id, transformed); return { code: transformed, map: null }; } }; } export default defineConfig({ // Disable shared legacy SSR config in favor of isolated environments environments: { node: { build: { outDir: 'dist/node', }, resolve: { conditions: ['node', 'import', 'module', 'default'], }, consumer: 'server', }, edge: { build: { outDir: 'dist/edge', }, resolve: { conditions: ['worker', 'workerd', 'edge-light', 'import', 'default'], noExternal: true, }, consumer: 'server', } }, plugins: [isolatedEnvironmentPlugin()] }); ```

Architectural Specification & Invariant Rationale

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

Vite 6 Environment API Multi-Runtime State Partitioning & Module Graph Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation of module graphs, transform pipelines, and memory spaces between Edge (WinterCG) and Node.js SSR runtimes during concurrent compilation under Vite 6. Prevents cross-runtime symbol contamination, shared plugin closure state leaks, and invalid platform polyfill resolution in unified micro-frontend monorepos. 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 State Sharing and Cross-Runtime Module Graph Pollution in Concurrent 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 State Sharing and Cross-Runtime Module Graph Pollution in Concurrent 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 isolate runtime target definitions under explicit `environments.<name>` configuration records, designating dedicated `resolve.conditions` and `consumer` profiles per runtime.

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.