Vite 6 Multi-Runtime Environment API and Per-Environment HMR Isolation

--- description: Vite 6 Multi-Runtime Environment API and Per-Environment HMR Isolation - Enforces strict isolation of execution contexts (workerd, node, edge, client) using Vite 6's Environment API and ModuleRunner architecture. Prohibits legacy Vite 5 SSR APIs, cross-environment runtime pollution, and un-scoped HMR event broadcasting across independent runtime boundary graphs. globs: vite.config.{ts,js,mjs}, src/**/*.{ts,tsx}, server/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-environment-api-runtime-isolation" --- # Vite 6 Multi-Runtime Environment API and Per-Environment HMR Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Node-specific APIs into edge/workerd environments and relying on legacy ssrLoadModule or root WebSocket broadcasting for SSR HMR. ## System Constraints You are a Principal Software Architect enforcing Vite 6 Environment API and Multi-Runtime isolation. Vite 6 decouples the client and server execution contexts into distinct environments (e.g., client, ssr, workerd, edge) each with dedicated module graphs, transform pipelines, and HMR communication channels. You must prohibit deprecated Vite 5 APIs (e.g., `server.ssrLoadModule`, `server.ssrTransform`, `server.ws.send`), eliminate runtime global pollution across environment boundaries, and enforce targeted per-environment HMR event emission via `environment.hot`. ## Strict Guidelines - Engineers MUST ALWAYS query and branch logic using `this.environment.name` inside Vite plugin hooks (e.g., `resolveId`, `load`, `transform`) instead of the deprecated `options?.ssr` boolean flag. - Engineers MUST ALWAYS execute server-side code using Vite 6 `ModuleRunner` or `server.environments[name].runner.import()` rather than the deprecated `server.ssrLoadModule()`. - Engineers MUST ALWAYS route environment-specific hot module updates through `environment.hot.send()` or `server.environments[name].hot.send()` instead of broadcasting indiscriminately via `server.ws.send()`. - Code targeting edge or web-worker runtimes (e.g., `workerd`) MUST NOT import or bundle Node.js built-ins (`fs`, `path`, `node:crypto`); resolve conditions must enforce runtime-compatible shims per environment configuration. - Custom Vite plugins MUST implement the `hotUpdate(options)` hook by checking `options.environment.name` to prevent cross-runtime invalidation loops between client and edge environments. - Multi-environment configurations MUST explicitly define `builder.buildApp` or separate `environments` targets in `vite.config.ts` to prevent shared module graph contamination during production builds. ## Bad vs Good Implementations ### Vite 6 Multi-Runtime Configuration and Per-Environment HMR Invariant #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The bad code relies on legacy Vite 5 patterns: using `options.ssr` inside `transform` (which collapses multi-runtime targets into a binary state), broadcasting HMR notifications across all clients via `server.ws.send`, and using the deprecated `server.ssrLoadModule` which cannot target isolated non-Node runtimes like workerd. ```typescript import { defineConfig, type ViteDevServer } from 'vite'; // ANTI-PATTERN: Vite 5 style plugin using legacy SSR flag, global ws broadcast, and ssrLoadModule export default defineConfig({ plugins: [{ name: 'custom-ssr-bridge', transform(code, id, options) { // Flawed: Boolean flag does not differentiate between Node, Edge, or Workerd runtimes if (options?.ssr) { return code.replace('__RUNTIME__', '"node"'); } return code.replace('__RUNTIME__', '"client"'); }, handleHotUpdate({ server, modules }) { // Flawed: Global broadcast triggers client reload for server-only worker changes server.ws.send({ type: 'custom', event: 'server-module-updated', data: { paths: modules.map(m => m.url) } }); } }] }); export async function runServerCode(server: ViteDevServer, entryUrl: string) { // Flawed: ssrLoadModule is deprecated in Vite 6 and bypasses the Environment ModuleRunner return await server.ssrLoadModule(entryUrl); } ``` #### Production Standard (Correct) > **Standard**: The good code leverages Vite 6's Environment API: explicitly declaring separate environments (`client`, `ssr`, `edge`), inspecting `this.environment.name` in plugin transforms, isolating HMR notifications to the specific `environment.hot` transport channel, and importing server modules through the decoupled `server.environments[name].runner` instance. ```typescript import { defineConfig, type ViteDevServer } from 'vite'; export default defineConfig({ environments: { client: { build: { outDir: 'dist/client' } }, ssr: { build: { outDir: 'dist/ssr' } }, edge: { resolve: { conditions: ['workerd', 'worker'] }, build: { outDir: 'dist/edge' } } }, plugins: [{ name: 'custom-ssr-bridge', transform(code, id) { // Invariant: Use this.environment.name for explicit multi-runtime branching const runtimeName = this.environment.name; return code.replace('__RUNTIME__', JSON.stringify(runtimeName)); }, hotUpdate({ environment, modules }) { // Invariant: Isolate HMR events strictly to the affected environment's channel environment.hot.send({ type: 'custom', event: `${environment.name}:module-updated`, data: { paths: modules.map(m => m.url) } }); } }] }); export async function runServerCode(server: ViteDevServer, envName: 'ssr' | 'edge', entryUrl: string) { // Invariant: Vite 6 ModuleRunner retrieved from explicit environment registry const env = server.environments[envName]; if (!env) { throw new Error(`Environment ${envName} not configured`); } const runner = env.runner; return await runner.import(entryUrl); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Multi-Runtime Environment API and Per-Environment HMR Isolation

Vite 6 Multi-Runtime Environment API and Per-Environment HMR Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation of execution contexts (workerd, node, edge, client) using Vite 6's Environment API and ModuleRunner architecture. Prohibits legacy Vite 5 SSR APIs, cross-environment runtime pollution, and un-scoped HMR event broadcasting across independent runtime boundary graphs. 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: Leaking Node-specific APIs into edge/workerd environments and relying on legacy ssrLoadModule or root WebSocket broadcasting for SSR HMR. 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	Leaking Node-specific APIs into edge/workerd environments and relying on legacy ssrLoadModule or root WebSocket broadcasting for SSR HMR.	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 query and branch logic using `this.environment.name` inside Vite plugin hooks (e.g., `resolveId`, `load`, `transform`) instead of the deprecated `options?.ssr` boolean flag.

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.