Vite 6 Environment API Runtime Module Isolation and Evaluation Boundary

--- description: Vite 6 Environment API Runtime Module Isolation and Evaluation Boundary - Enforces strict runtime module graph isolation between Workerd, Node.js, and Client environments within Vite 6 multi-environment configurations. Prevents execution graph poisoning, cross-runtime prototype pollution, and illegal native binding leakage across heterogeneous SSR execution targets. globs: vite.config.ts, vite.config.*.ts, src/entry.server.ts, src/entry.workerd.ts, src/entry.client.ts, src/server/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-environment-runtime-module-isolation-boundary" --- # Vite 6 Environment API Runtime Module Isolation and Evaluation Boundary > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Module Graph Leakage and Heterogeneous Runtime Pollution in Multi-Target Vite 6 SSR ## System Constraints You are a Principal Software Architect enforcing runtime module boundaries in Vite 6 Environment API multi-target architectures. You must prevent cross-contamination between client, Node.js, and Workerd module graphs. Mandate isolated DevEnvironments, environment-specific resolve conditions, distinct ModuleRunners, and explicit boundaries against importing Node.js built-ins into edge runtimes. ## Strict Guidelines - Engineers MUST ALWAYS declare isolated environments using the Vite 6 `environments` top-level configuration key instead of relying on root-level SSR options. - Engineers MUST configure explicit runtime `resolve.conditions` per environment (e.g., `['workerd', 'worker']` for Cloudflare Workers vs `['node']` for Node.js runtime). - Engineers MUST NOT invoke deprecated `server.ssrLoadModule` when targeting heterogeneous runtimes; dynamic evaluations MUST execute via the respective `environment.runner.import()` bound to that specific `DevEnvironment`. - Module runners executing inside non-Node runtimes MUST communicate across processes via decoupled RPC transports rather than shared in-memory references. - Code targeting Workerd environments MUST NEVER import or re-export Node.js native primitives (such as `node:fs` or `node:child_process`) unless supported by specific runtime compatibility flags. - Plugins MUST inspect `this.environment.name` inside lifecycle hooks (`resolveId`, `load`, `transform`) to ensure transforms are selectively applied only to the corresponding runtime graph. ## Bad vs Good Implementations ### Vite 6 Multi-Environment Module Graph Isolation Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: This legacy Vite pattern shares a single module graph and unified resolve conditions across client and server. Node-specific and Workerd-specific code resolve ambiguously, leading to runtime failures when Node built-ins or Workerd-specific polyfills leak into the wrong evaluation target. ```typescript import { defineConfig } from 'vite'; // ANTI-PATTERN: Merging Workerd and Node SSR into a single module graph with ambiguous resolution export default defineConfig({ ssr: { target: 'webworker', noExternal: true, }, resolve: { // Pollutes client, Node, and Workerd with identical conditions conditions: ['workerd', 'node', 'import'] }, server: { // Single global SSR runner leaking Node globals into worker modules } }); ``` #### Production Standard (Correct) > **Standard**: Defines explicit Vite 6 environments (`client`, `node`, `workerd`) with distinct module graphs, runtime conditions, and independent compilation targets. Workerd execution is isolated using a dedicated dev environment runner, preventing cross-runtime pollution. ```typescript import { defineConfig } from 'vite'; import { workerdDevEnvironment } from 'vite-environment-workerd'; export default defineConfig({ environments: { client: { build: { outDir: 'dist/client' } }, node: { resolve: { conditions: ['node', 'import'] }, build: { outDir: 'dist/node', ssr: true } }, workerd: { dev: { createEnvironment(name, config) { return workerdDevEnvironment(name, config, { entry: 'src/entry.workerd.ts', compatibilityFlags: ['nodejs_compat'] }); } }, resolve: { conditions: ['workerd', 'worker', 'browser', 'import'], noExternal: true }, build: { outDir: 'dist/workerd', ssr: true } } } }); ``` ### Runtime Module Evaluation via Environment Runner Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling `server.ssrLoadModule` forces execution through Node's VM context using Node's module graph, failing to evaluate Worker-specific APIs and polluting Workerd code with Node runtime bindings. ```typescript import type { ViteDevServer } from 'vite'; // ANTI-PATTERN: Using ssrLoadModule from root server across heterogeneous runtimes export async function handleRequest(server: ViteDevServer, url: string) { // Leaks the host Node.js environment into the workerd execution context const entry = await server.ssrLoadModule('/src/entry.workerd.ts'); return entry.default.fetch(new Request(url)); } ``` #### Production Standard (Correct) > **Standard**: Accesses the Workerd-specific `DevEnvironment` directly from `server.environments` and uses its dedicated `ModuleRunner`. This guarantees the module is transformed, resolved, and evaluated exclusively within the Workerd graph boundary. ```typescript import type { ViteDevServer } from 'vite'; export async function handleRequest(server: ViteDevServer, url: string) { const workerdEnv = server.environments.workerd; if (!workerdEnv) { throw new Error('Workerd environment not configured in Vite runtime'); } // Access isolated module runner specific to the workerd DevEnvironment const entry = await workerdEnv.runner.import('/src/entry.workerd.ts'); return entry.default.fetch(new Request(url)); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Runtime Module Isolation and Evaluation Boundary

Vite 6 Environment API Runtime Module Isolation and Evaluation Boundary defines an industrial-grade behavioral standard for frontend engineering. Enforces strict runtime module graph isolation between Workerd, Node.js, and Client environments within Vite 6 multi-environment configurations. Prevents execution graph poisoning, cross-runtime prototype pollution, and illegal native binding leakage across heterogeneous SSR execution targets. 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 Module Graph Leakage and Heterogeneous Runtime Pollution in Multi-Target Vite 6 SSR 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 Module Graph Leakage and Heterogeneous Runtime Pollution in Multi-Target Vite 6 SSR	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 declare isolated environments using the Vite 6 `environments` top-level configuration key instead of relying on root-level SSR options.

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.