Vite 6 Environment API Module-Graph Isolation Standard

--- description: Vite 6 Environment API Module-Graph Isolation Standard - Enforces strict module-graph separation and runtime-targeted execution via Vite 6 Environment APIs across browser, SSR, and edge environments. Prevents cross-runtime state leakage, invalid Node.js/browser primitive cross-contamination, and shared plugin cache corruption during multi-runtime builds. globs: vite.config.ts, vite.config.*.ts, src/**/*.{ts,tsx,js,jsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-environment-api-isolation-production-standard" --- # Vite 6 Environment API Module-Graph Isolation Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Monolithic Module Graph Traversal and Shared Plugin State Across Disparate Runtime Environments ## System Constraints You are a Principal Software Architect enforcing the Vite 6 Environment API Isolation Standard. You must mandate strict isolation of module graphs, plugin lifecycle contexts, and resolution pipelines across distinct target runtimes (e.g., client, ssr, edge/workerd). Eliminate legacy dual-build hacks, deprecated `server.ssrLoadModule` workflows, and shared in-memory caches that fail to key on runtime environment instances. ## Strict Guidelines - Engineers MUST ALWAYS configure multi-runtime builds using Vite 6 `environments` options (e.g., `environments.client`, `environments.ssr`, `environments.edge`) rather than spawning disparate top-level Vite instances or relying on ad-hoc boolean `ssr` flags. - Engineers MUST NOT access `server.moduleGraph` or `server.ssrLoadModule` when targeting Vite 6; use `server.environments[name].moduleGraph` and `server.environments[name].runner.import` instead. - Plugin authors MUST use `this.environment` inside plugin hooks (`resolveId`, `load`, `transform`) to query runtime context and target-specific configs instead of relying on global process state or root plugin options. - Code MUST partition all in-memory compilation caches using `this.environment.name` as a primary namespace key to prevent client and SSR transforms from polluting each other. - Services MUST declare explicit runtime builtins isolation using `resolve.conditions` and `resolve.externalConditions` scoped strictly per environment block in `vite.config.ts`. - Components and application code NEVER rely on non-standard runtime ambient globals; they must undergo runtime boundary separation verified by environment-specific resolution. ## Bad vs Good Implementations ### Vite 6 Config: Multi-Runtime Environment Declaration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Relies on legacy boolean SSR flags and environment-unaware build configurations. This causes cross-compilation leakage where worker and browser resolution pipelines bleed together, and shared plugin state corrupts transformed outputs. ```typescript import { defineConfig } from 'vite'; // ANTI-PATTERN: Vite 5 legacy config relying on unified module graph and boolean SSR toggle export default defineConfig({ build: { ssr: process.env.IS_SSR === 'true', }, ssr: { target: 'webworker', noExternal: true, }, plugins: [ { name: 'leaky-cache-plugin', transform(code, id, options) { // Boolean options.ssr flag lacks runtime environment isolation if (options?.ssr) { return code.replace('__TARGET__', 'ssr'); } return code.replace('__TARGET__', 'client'); }, }, ], }); ``` #### Production Standard (Correct) > **Standard**: Defines isolated compilation pipelines via Vite 6 `environments`. Guarantees deterministic module-graph separation for client, SSR, and edge runtimes with strict resolution conditions and environment-scoped plugin hooks. ```typescript import { defineConfig } from 'vite'; // PRODUCTION INVARIANT: Vite 6 isolated Environment API configuration export default defineConfig({ environments: { client: { build: { outDir: 'dist/client', }, resolve: { conditions: ['browser', 'import'], }, }, ssr: { build: { outDir: 'dist/ssr', }, resolve: { conditions: ['node', 'import'], externalConditions: ['node'], }, }, edge: { build: { outDir: 'dist/edge', }, resolve: { conditions: ['worker', 'workerd', 'import'], noExternal: true, }, }, }, plugins: [ { name: 'isolated-environment-plugin', transform(code, id) { // Access isolated environment context per module graph const envName = this.environment.name; return { code: code.replace('__TARGET__', envName), map: null, }; }, }, ], }); ``` ### Custom Dev Server Execution: Environment Runner Migration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses deprecated `server.ssrLoadModule` and the monolithic `server.moduleGraph`, mixing client HMR state with server evaluation and leaking server-side state into client-bound module nodes. ```typescript import { createServer } from 'vite'; // ANTI-PATTERN: Deprecated server.ssrLoadModule and global moduleGraph traversal async function handleRequest(url: string) { const server = await createServer({ server: { middlewareMode: true } }); // Mutates and traverses monolithic module graph directly const mod = await server.moduleGraph.getModuleByUrl(url); const entry = await server.ssrLoadModule('/src/entry.server.ts'); return entry.render(url); } ``` #### Production Standard (Correct) > **Standard**: Accesses the runtime through `server.environments.ssr` and executes code via its isolated `RunnableDevEnvironment.runner`. Guarantees complete separation of the SSR execution context and module graph from client assets. ```typescript import { createServer } from 'vite'; import type { RunnableDevEnvironment } from 'vite'; // PRODUCTION INVARIANT: Vite 6 Environment-scoped runner and moduleGraph access async function handleRequest(url: string) { const server = await createServer({ appType: 'custom', server: { middlewareMode: true }, }); // Retrieve strictly isolated environment context const ssrEnvironment = server.environments.ssr; if (!('runner' in ssrEnvironment)) { throw new Error('SSR environment must be configured as a RunnableDevEnvironment'); } const runnableEnv = ssrEnvironment as RunnableDevEnvironment; // Inspect isolated module graph specific to SSR execution const mod = await runnableEnv.moduleGraph.getModuleByUrl(url); // Execute within isolated ModuleRunner sandbox const entry = await runnableEnv.runner.import('/src/entry.server.ts'); return entry.render(url); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Module-Graph Isolation Standard

Vite 6 Environment API Module-Graph Isolation Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict module-graph separation and runtime-targeted execution via Vite 6 Environment APIs across browser, SSR, and edge environments. Prevents cross-runtime state leakage, invalid Node.js/browser primitive cross-contamination, and shared plugin cache corruption during multi-runtime builds. 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 Traversal and Shared Plugin State Across Disparate Runtime 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	Monolithic Module Graph Traversal and Shared Plugin State Across Disparate Runtime 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 configure multi-runtime builds using Vite 6 `environments` options (e.g., `environments.client`, `environments.ssr`, `environments.edge`) rather than spawning disparate top-level Vite instances or relying on ad-hoc boolean `ssr` flags.

Engineers MUST ALWAYS configure multi-runtime builds using Vite 6 `environments` options (e.g., `environments.client`, `environments.ssr`, `environments.edge`) rather than spawning disparate top-level Vite instances or relying on ad-hoc boolean `ssr` flags.

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.