Vite 6 Environment API Multi-Runtime Module Sandboxing Standard

--- description: Vite 6 Environment API Multi-Runtime Module Sandboxing Standard - Enforces strict runtime boundary isolation when cross-compiling shared libraries across browser, edge, Node.js, and workerd targets within a single Vite 6 dev server instance. Guarantees that module graphs, resolve conditions, and transform pipelines remain sandboxed to prevent runtime global contamination and invalid target execution. globs: vite.config.ts, vite.config.*.ts, src/**/*.{ts,tsx}, server/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-environment-api-runtime-sandboxing" --- # Vite 6 Environment API Multi-Runtime Module Sandboxing Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-contaminating module graphs and resolve conditions across browser, workerd, and Node.js runtimes using legacy single-target Vite paradigms. ## System Constraints You are a Principal Software Architect enforcing Vite 6 Environment API multi-runtime module sandboxing. Vite 6 decouples the client and SSR build pipelines into isolated DevEnvironments (e.g., client, ssr, edge, workerd). You must ensure all configurations, plugins, and imports strictly maintain runtime boundary isolation, prevent cross-environment cache contamination, and reject legacy ssrLoadModule patterns. ## Strict Guidelines - Engineers MUST ALWAYS configure runtime targets using the Vite 6 top-level `environments` configuration key instead of legacy overloaded `ssr` or conditional plugin arrays. - Engineers MUST ALWAYS qualify plugin caches and transform states with `this.environment.name` inside Vite plugin hooks to prevent cross-runtime AST or bytecode leakage. - Engineers MUST NOT use deprecated `server.ssrLoadModule()` or `server.ssrFixStacktrace()`; invoke `server.environments[name].runner.runModule()` or `server.environments[name].runner.import()` instead. - Code executing in the `workerd` or `edge` environment MUST NOT import Node.js built-ins (`node:fs`, `node:path`, `node:child_process`) unless explicitly shimmed or aliased for that specific environment. - Plugins targeting multiple environments MUST use per-environment hook definitions (`applyToEnvironment(environment)` or inspect `this.environment.name`) to enforce deterministic compilation paths. - Services MUST define explicit, non-overlapping `resolve.conditions` for each runtime environment (e.g., `['workerd', 'worker']` vs `['node', 'import']` vs `['browser']`). ## Bad vs Good Implementations ### Multi-Runtime Environment Configuration with Isolated Conditions #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Configuring runtimes via legacy `ssr` flags and global `resolve.conditions` causes export condition cross-contamination, causing Node.js or browser-specific modules to leak into Cloudflare workerd/edge runtimes. The plugin cache is shared globally across runtimes without environment scoping. ```typescript import { defineConfig } from 'vite'; // Anti-pattern: Monolithic config with overlapping SSR flags // Leaks Node.js resolution into workerd and relies on global ssr condition export default defineConfig({ ssr: { target: 'webworker', noExternal: true, }, resolve: { // Problematic: global conditions leak across client and server conditions: ['workerd', 'browser', 'node'], }, plugins: [ { name: 'leaky-cache-plugin', transform(code, id) { // Problematic: shared memory cache across runtimes globalTransformCache.set(id, code); return code; }, }, ], }); ``` #### Production Standard (Correct) > **Standard**: Uses the Vite 6 `environments` API to strictly sandbox `client`, `workerd`, and `node` runtimes with isolated `resolve.conditions` and `consumer` roles. Plugin hooks scope cached artifacts by `this.environment.name` to prevent cross-runtime contamination. ```typescript import { defineConfig } from 'vite'; const environmentScopedCache = new Map<string, Map<string, string>>(); export default defineConfig({ environments: { client: { resolve: { conditions: ['browser', 'module'], }, consumer: 'client', }, workerd: { resolve: { conditions: ['workerd', 'worker', 'import'], external: ['cloudflare:workers'], }, consumer: 'server', }, node: { resolve: { conditions: ['node', 'import'], }, consumer: 'server', }, }, plugins: [ { name: 'isolated-runtime-plugin', transform(code, id) { const envName = this.environment.name; if (!environmentScopedCache.has(envName)) { environmentScopedCache.set(envName, new Map()); } const envCache = environmentScopedCache.get(envName)!; envCache.set(id, code); return code; }, }, ], }); ``` ### Programmatic Module Execution via Environment Runner #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling `server.ssrLoadModule` forces execution through the default Node.js SSR runtime, completely bypassing custom environment runtimes (like edge or workerd) and breaking module sandboxing. ```typescript import type { ViteDevServer } from 'vite'; // Anti-pattern: Invoking deprecated server.ssrLoadModule // Ignores target environment sandboxes and defaults unconditionally to Node ssr export async function executeHandler(server: ViteDevServer, entryUrl: string) { const mod = await server.ssrLoadModule(entryUrl); return mod.default; } ``` #### Production Standard (Correct) > **Standard**: Uses Vite 6's `server.environments[name].runner.import()` to dynamically execute the module graph inside the exact, isolated execution context configured for that target runtime. ```typescript import type { ViteDevServer } from 'vite'; export async function executeHandler( server: ViteDevServer, environmentName: 'node' | 'workerd', entryUrl: string ) { const environment = server.environments[environmentName]; if (!environment) { throw new Error(`Environment '${environmentName}' is not configured in Vite server.`); } // Vite 6: Execute within the isolated runtime runner of the specified environment const mod = await environment.runner.import(entryUrl); return mod.default; } ```

Architectural Specification & Invariant Rationale

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

Vite 6 Environment API Multi-Runtime Module Sandboxing Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict runtime boundary isolation when cross-compiling shared libraries across browser, edge, Node.js, and workerd targets within a single Vite 6 dev server instance. Guarantees that module graphs, resolve conditions, and transform pipelines remain sandboxed to prevent runtime global contamination and invalid target execution. 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-contaminating module graphs and resolve conditions across browser, workerd, and Node.js runtimes using legacy single-target Vite paradigms. 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-contaminating module graphs and resolve conditions across browser, workerd, and Node.js runtimes using legacy single-target Vite paradigms.	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 runtime targets using the Vite 6 top-level `environments` configuration key instead of legacy overloaded `ssr` or conditional plugin arrays.

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.