Vite 6 Environment API Runtime Module Isolation Guardrail

--- description: Vite 6 Environment API Runtime Module Isolation Guardrail - Enforces strict boundary isolation and prevents cross-runtime prototype pollution and state leakage across browser, web worker/worklet, and server-side runtime graphs using the Vite 6 Environment API. Guarantees that compilation transforms, dependency caches, and ModuleRunner instances operate within deterministic, hermetically isolated runtime execution contexts. globs: vite.config.{ts,js,mjs}, src/**/*.{ts,tsx,js,jsx}, server/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-environment-api-runtime-isolation-guardrail" --- # Vite 6 Environment API Runtime Module Isolation Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Runtime State Bleed and Shared Module Graph Pollution via Legacy Vite SSR Loaders ## System Constraints You are a Principal Software Architect enforcing the Vite 6 Environment API Runtime Module Isolation Guardrail. You must prohibit legacy vite SSR single-graph evaluation patterns (`ssrLoadModule`), require explicit per-environment configuration (`client`, `ssr`, `worklet`, `edge`), enforce isolated `ModuleRunner` instances with hermetic module transports, and ensure plugins strictly branch or isolate their transform/resolve hooks using `this.environment` to eliminate cross-runtime prototype pollution. ## Strict Guidelines - Engineers MUST ALWAYS configure distinct environments within `environments` configuration blocks in Vite 6, declaring explicit build targets, resolve conditions, and runtime boundaries for each environment (e.g., client, ssr, worklet). - Engineers MUST NOT use deprecated legacy `server.ssrLoadModule()` or unisolated Node-level `eval` for server or edge execution; all isolated evaluations MUST be conducted through Vite 6 `ModuleRunner` with explicit transports. - Plugins MUST ALWAYS scope resolution and transformation behaviors by querying `this.environment.name` inside lifecycle hooks rather than assuming a universal global environment or relying on ambiguous `options.ssr` flags. - Shared utilities across multiple execution boundaries MUST remain strictly pure; they NEVER mutate `globalThis`, native prototypes (`Object.prototype`, `Array.prototype`), or runtime global singletons shared between worker threads and the main process. - Module runners for headless or isolated execution graphs (e.g., AudioWorklet, Edge Workers) MUST use isolated evaluator contexts (`ESMRunner` or dedicated worker contexts) to prevent sandbox escapes and global scope contamination. ## Bad vs Good Implementations ### Vite 6 Configuration and Plugin Environment Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The legacy SSR configuration treats execution as a simplistic client-versus-server binary. Mutating globalThis directly causes prototype contamination and shared state leaks across concurrent SSR runs, worker runtimes, and client compilation pipelines. ```typescript // Anti-pattern: Relying on legacy implicit SSR config, sharing mutable module graphs, // and using ambiguous `ssr` flags that leak Node globals into worklets/client bundles. import { defineConfig } from 'vite'; export default defineConfig({ ssr: { noExternal: true, }, plugins: [{ name: 'leaky-plugin', resolveId(id, importer, options) { // Flawed assumption: Binary client vs SSR check leaks edge and worklet runtimes if (options?.ssr) { // Pollutes global prototype in SSR execution context directly (globalThis as unknown as { __CACHE__: Map<string, unknown> }).__CACHE__ = new Map(); return id.replace('$runtime', 'node-runtime'); } return null; }, }], }); ``` #### Production Standard (Correct) > **Standard**: Declares explicit hermetic environments (`client`, `ssr`, `worklet`) and inspects `this.environment.name` in plugin hooks. Avoids runtime prototype pollution by avoiding shared global caches and cleanly separating module resolutions for heterogeneous execution targets. ```typescript // Production standard: Vite 6 Environment API with explicitly isolated execution contexts import { defineConfig, type Plugin } from 'vite'; export default defineConfig({ environments: { client: { consumer: 'client', build: { outDir: 'dist/client' }, }, ssr: { consumer: 'server', build: { outDir: 'dist/ssr' }, resolve: { conditions: ['node', 'import'] }, }, worklet: { consumer: 'client', build: { outDir: 'dist/worklet' }, resolve: { noExternal: true, conditions: ['worklet', 'browser'] }, }, }, plugins: [{ name: 'isolated-env-plugin', resolveId(id) { // Guarantees deterministic module resolution per discrete execution boundary if (this.environment.name === 'worklet') { return id.includes('$runtime') ? '\0worklet-runtime' : null; } if (this.environment.name === 'ssr') { return id.includes('$runtime') ? '\0ssr-runtime' : null; } return null; }, load(id) { if (id === '\0ssr-runtime') { return 'export const getLocalStore = () => new Map();'; } if (id === '\0worklet-runtime') { return 'export const getLocalStore = () => Object.freeze({});'; } return null; }, } as Plugin], }); ``` ### Module Runner Instantiation vs Legacy ssrLoadModule #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: `ssrLoadModule` is part of Vite's legacy evaluation flow and executes within the dev server's main Node process, sharing singletons and causing non-deterministic cross-request prototype pollution. ```typescript // Anti-pattern: Using deprecated server.ssrLoadModule directly in Vite 6 import type { ViteDevServer } from 'vite'; export async function handleRequest(server: ViteDevServer, url: string) { // Leaks evaluation into the parent Node.js Vite server process const entry = await server.ssrLoadModule('/src/entry.server.ts'); return entry.render(url); } ``` #### Production Standard (Correct) > **Standard**: Instantiates a dedicated Vite 6 `ModuleRunner` with an explicit `ESMRunner` evaluator and `createServerModuleRunnerTransport`. This ensures evaluation runs in an isolated runner context bound specifically to the SSR environment without polluting the host Vite process. ```typescript // Production standard: Vite 6 ModuleRunner with isolated runner transport import { createServer } from 'vite'; import { ModuleRunner, createServerModuleRunnerTransport } from 'vite/module-runner'; export async function createIsolatedRenderer() { const server = await createServer(); const ssrEnvironment = server.environments.ssr; // Construct an isolated ModuleRunner bound strictly to the SSR DevEnvironment const runner = new ModuleRunner( { root: server.config.root, transport: createServerModuleRunnerTransport({ environment: ssrEnvironment }), }, // Sandboxed evaluator preventing prototype leakage into the host server new (await import('vite/module-runner')).ESMRunner() ); return { async render(url: string) { const entry = await runner.import('/src/entry.server.ts'); return entry.render(url); }, async close() { await runner.close(); await server.close(); }, }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Runtime Module Isolation Guardrail

Vite 6 Environment API Runtime Module Isolation Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary isolation and prevents cross-runtime prototype pollution and state leakage across browser, web worker/worklet, and server-side runtime graphs using the Vite 6 Environment API. Guarantees that compilation transforms, dependency caches, and ModuleRunner instances operate within deterministic, hermetically isolated runtime execution contexts. 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: Cross-Runtime State Bleed and Shared Module Graph Pollution via Legacy Vite SSR Loaders 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	Cross-Runtime State Bleed and Shared Module Graph Pollution via Legacy Vite SSR Loaders	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 distinct environments within `environments` configuration blocks in Vite 6, declaring explicit build targets, resolve conditions, and runtime boundaries for each environment (e.g., client, ssr, worklet).

Engineers MUST ALWAYS configure distinct environments within `environments` configuration blocks in Vite 6, declaring explicit build targets, resolve conditions, and runtime boundaries for each environment (e.g., client, ssr, worklet).

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.