Vite 6 Environment API Multi-Runtime Module Graph Isolation Standard

--- description: Vite 6 Environment API Multi-Runtime Module Graph Isolation Standard - Enforces strict isolation of module graphs, transform pipelines, and execution runtimes across multi-target SSR architectures using Vite 6's Environment API. Eliminates cross-runtime state pollution, illegal host-runtime API leaks, and redundant module transformations across Client, Node.js, and WinterCG workerd environments. globs: vite.config.{ts,js,mjs}, src/**/*.{ts,tsx}, server/**/*.{ts,js,mjs} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-environment-api-runtime-boundary-standard-vite-6-environme-374" --- # Vite 6 Environment API Multi-Runtime Module Graph Isolation Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Monolithic Module Graph Bleed and Deprecated ssrLoadModule Usage Across Disjoint Runtimes ## System Constraints You are a Principal Software Architect enforcing Vite 6 Environment API Runtime Boundaries. You MUST reject deprecated monolithic Vite 5 patterns such as server.ssrLoadModule, un-scoped server.moduleGraph queries, and shared mutable state across heterogeneous runtimes. Enforce isolated DevEnvironment instances, per-environment runner imports, explicit resolve conditions, and separate module graphs for client, node, and edge/wintercg targets. ## Strict Guidelines - Engineers MUST ALWAYS instantiate isolated runtimes via Vite 6 `server.environments[name]` rather than legacy root-level SSR APIs. - Engineers MUST NOT invoke `server.ssrLoadModule` or `server.ssrFixStacktrace`; use `server.environments[name].runner.import()` and environment-scoped error mappers instead. - Plugins MUST configure per-environment hooks using `applyToEnvironment(environment)` or inspect `this.environment` rather than inspecting global `ssr` boolean flags. - Vite configurations targeting heterogeneous runtimes (e.g., Client + Cloudflare Workerd + Node) MUST declare explicit environment entries with dedicated `consumer`, `resolve.conditions`, and `nodeCompat` settings. - Module graphs MUST NOT share in-memory singletons across runtime boundaries; all cross-boundary communication must traverse serialized IPC or structured clone interfaces. - Custom dev runtime runners MUST implement `ModuleRunnerTransport` and process module evaluation inside strictly isolated VM contexts or separate runtime workers. ## Bad vs Good Implementations ### Configuring Isolated Environments in vite.config.ts #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Configuring target and conditions globally on the root config causes module resolution leaks across the browser and worker graphs, leading to Node built-ins leaking into edge bundles and invalid package exports resolution. ```typescript import { defineConfig } from 'vite'; // ANTI-PATTERN: Monolithic SSR configuration attempting to multiplex // WinterCG (workerd) and Node runtimes via a single ssr block export default defineConfig({ ssr: { target: 'webworker', noExternal: true, }, resolve: { // Pollutes client and SSR module graphs with conflicting condition flags conditions: ['worker', 'workerd', 'browser'], }, }); ``` #### Production Standard (Correct) > **Standard**: Declares explicit environments with dedicated resolve conditions, module graph isolation, and discrete build lifecycles via the builder API. ```typescript import { defineConfig } from 'vite'; // PRODUCTION INVARIANT: Vite 6 Environment API with discrete ModuleGraph definitions export default defineConfig({ environments: { client: { consumer: 'client', resolve: { conditions: ['browser', 'module'], }, }, ssr: { consumer: 'server', resolve: { conditions: ['node', 'import'], externalConditions: ['node', 'import'], }, nodeCompat: true, }, edge: { consumer: 'server', resolve: { conditions: ['workerd', 'worker', 'import'], noExternal: true, }, }, }, builder: { buildApp: async (builder) => { await Promise.all([ builder.build(builder.environments.client), builder.build(builder.environments.ssr), builder.build(builder.environments.edge), ]); }, }, }); ``` ### Invoking Dev Server Runtime via ModuleRunner API #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: server.ssrLoadModule forces execution within the host Node process, bypasses custom environment runtimes (like Workerd/Deno), and corrupts the module graph when handling multi-environment invalidations. ```typescript import type { ViteDevServer } from 'vite'; // ANTI-PATTERN: Deprecated Vite 5 ssrLoadModule invocation on root server export async function handleRequest(server: ViteDevServer, url: string) { // Leaks monolithic Node.js runtime state; fails silently under non-Node target runtimes const entry = await server.ssrLoadModule('/src/entry-server.ts'); server.ssrFixStacktrace(new Error('test')); return entry.render(url); } ``` #### Production Standard (Correct) > **Standard**: Retrieves the dedicated DevEnvironment instance and executes the module through its configured runner, ensuring transforms, hot updates, and globals adhere solely to that environment's sandbox. ```typescript import type { ViteDevServer } from 'vite'; import type { DevEnvironment } from 'vite'; // PRODUCTION INVARIANT: Per-environment scoped execution using ModuleRunner export async function handleRequest(server: ViteDevServer, url: string) { const edgeEnv: DevEnvironment = server.environments.edge; if (!edgeEnv || !edgeEnv.runner) { throw new Error('Edge environment runner is not initialized'); } // Strictly scoped to the 'edge' module graph and custom runtime transport const entry = await edgeEnv.runner.import('/src/entry-edge.ts'); return entry.default.fetch(new Request(url)); } ```

Architectural Specification & Invariant Rationale

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

Vite 6 Environment API Multi-Runtime Module Graph Isolation Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation of module graphs, transform pipelines, and execution runtimes across multi-target SSR architectures using Vite 6's Environment API. Eliminates cross-runtime state pollution, illegal host-runtime API leaks, and redundant module transformations across Client, Node.js, and WinterCG workerd environments. 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 Bleed and Deprecated ssrLoadModule Usage Across Disjoint Runtimes 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 Bleed and Deprecated ssrLoadModule Usage Across Disjoint Runtimes	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 instantiate isolated runtimes via Vite 6 `server.environments[name]` rather than legacy root-level SSR APIs.

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.