Vite 6 Environment API Multi-Runtime Isolation and Scoped HMR Invariant

--- description: Vite 6 Environment API Multi-Runtime Isolation and Scoped HMR Invariant - Vite 6 establishes independent runtime environments (client, ssr, workerd, edge) each maintaining segregated module graphs, runners, and communication channels. Plugins and servers must use environment-scoped hooks (`this.environment`), explicit `ModuleRunner` instances, and isolated HMR channels rather than deprecated global module loaders or unified WebSocket broadcasts. 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-multi-runtime-isolation" --- # Vite 6 Environment API Multi-Runtime Isolation and Scoped HMR Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Runtime Graph Contamination and Unscoped Global HMR in Vite 6 Multi-Environment Setups ## System Constraints You are a Principal Software Architect enforcing Vite 6 Environment API invariants. Vite 6 breaks out of the monolithic SSR architecture by decoupling runtimes into isolated environments (e.g., client, ssr, edge, workerd). You must prevent module graph leakage across runtimes, eliminate legacy Vite 5 SSR APIs, mandate environment-aware plugin hooks via `this.environment`, and ensure HMR boundaries are cleanly separated using scoped hot channels. ## Strict Guidelines - Engineers MUST ALWAYS inspect `this.environment.name` inside Vite plugin lifecycle hooks (`resolveId`, `load`, `transform`) to isolate runtime-specific dependencies and prevent Node.js built-ins from leaking into edge/workerd runtimes. - Engineers MUST NOT invoke deprecated legacy APIs such as `server.ssrLoadModule()` or `server.ssrFixStacktrace()`; invoke the target runtime's runner via `server.environments[envName].runner.import()` or instantiate an explicit `ModuleRunner`. - Engineers MUST ALWAYS reference module nodes and invalidate caches via `server.environments[name].moduleGraph` instead of relying on top-level unified graph assumptions. - Engineers MUST dispatch custom HMR events using `environment.hot.send()` or `hot.send()` on the environment channel rather than `server.ws.send()`, preventing invalidation storms across incompatible target runtimes. - Plugins declaring custom runtimes MUST explicitly configure `resolve.conditions`, `resolve.external`, and `dev.createEnvironment` adhering to the constraints of the targeted runtime (e.g., Cloudflare workerd vs. Node.js). ## Bad vs Good Implementations ### Configuring Multi-Runtime Dev Environments and Targeted HMR Execution #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Legacy Vite 5 APIs (`server.ssrLoadModule`, global `server.ws.send`) violate Vite 6 environment separation. Injecting Node.js built-ins without inspecting `this.environment` causes compilation crashes in non-Node runtimes like workerd or edge environments. ```typescript import { defineConfig, type ViteDevServer, type Plugin } from 'vite'; export const leakyPlugin = (): Plugin => ({ name: 'leaky-plugin', transform(code, id) { // ANTI-PATTERN: Resolving node built-ins indiscriminately across all runtimes if (id.endsWith('.server.ts')) { return `import 'node:fs'; ${code}`; } return code; }, handleHotUpdate({ server, modules }) { // ANTI-PATTERN: Broadcasting updates globally across all runtimes server.ws.send({ type: 'custom', event: 'server-code-updated', data: { count: modules.length } }); } }); export async function executeServerModule(server: ViteDevServer, entryPoint: string) { // ANTI-PATTERN: Legacy Vite 5 ssrLoadModule deprecated in Vite 6 return await server.ssrLoadModule(entryPoint); } ``` #### Production Standard (Correct) > **Standard**: Leverages the Vite 6 Environment API: checks `this.environment.name` in plugin lifecycle hooks, uses the environment-scoped `hotUpdate` hook with `environment.hot.send`, and executes modules through `server.environments[name].runner.import()`. ```typescript import { defineConfig, type ViteDevServer, type Plugin } from 'vite'; export const runtimeIsolatedPlugin = (): Plugin => ({ name: 'runtime-isolated-plugin', transform(code, id) { // INVARIANT: Inspect this.environment.name to enforce runtime boundaries if (this.environment.name === 'edge' || this.environment.name === 'workerd') { if (code.includes('node:fs') || code.includes('node:path')) { this.error(`Forbidden Node built-in imported in ${this.environment.name} environment: ${id}`); } } return code; }, hotUpdate({ environment, modules }) { // INVARIANT: Dispatch HMR updates only to the affected environment runner environment.hot.send({ type: 'custom', event: 'environment-module-updated', data: { env: environment.name, paths: modules.map(m => m.url) } }); } }); export async function executeServerModule( server: ViteDevServer, environmentName: 'ssr' | 'workerd', entryPoint: string ) { // INVARIANT: Access the explicit DevEnvironment and its ModuleRunner instance const env = server.environments[environmentName]; if (!env || !('runner' in env)) { throw new Error(`Environment '${environmentName}' not configured or missing runner.`); } return await env.runner.import(entryPoint); } ```

Architectural Specification & Invariant Rationale

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

Vite 6 Environment API Multi-Runtime Isolation and Scoped HMR Invariant defines an industrial-grade behavioral standard for frontend engineering. Vite 6 establishes independent runtime environments (client, ssr, workerd, edge) each maintaining segregated module graphs, runners, and communication channels. Plugins and servers must use environment-scoped hooks (`this.environment`), explicit `ModuleRunner` instances, and isolated HMR channels rather than deprecated global module loaders or unified WebSocket broadcasts. 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 Graph Contamination and Unscoped Global HMR in Vite 6 Multi-Environment Setups 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 Graph Contamination and Unscoped Global HMR in Vite 6 Multi-Environment Setups	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 inspect `this.environment.name` inside Vite plugin lifecycle hooks (`resolveId`, `load`, `transform`) to isolate runtime-specific dependencies and prevent Node.js built-ins from leaking into edge/workerd runtimes.

Engineers MUST ALWAYS inspect `this.environment.name` inside Vite plugin lifecycle hooks (`resolveId`, `load`, `transform`) to isolate runtime-specific dependencies and prevent Node.js built-ins from leaking into edge/workerd runtimes.

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.