Vite 6 Multi-Runtime Environment API Isolation and HMR Scoping

--- description: Vite 6 Multi-Runtime Environment API Isolation and HMR Scoping - Vite 6 replaces the monolithic SSR architecture with the Environment API, providing isolated module graphs, runtime evaluators, and HMR communication per target runtime (e.g., client, Node.js SSR, Cloudflare workerd). Developers must strictly isolate runtime configurations, utilize runtime-specific ModuleRunner instances, and avoid cross-runtime module graph mutations or unscoped HMR broadcasts. globs: vite.config.{ts,js,mjs}, server/**/*.{ts,js,mjs}, src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-environment-api-multi-runtime-isolation-vite-6-environme-300" --- # Vite 6 Multi-Runtime Environment API Isolation and HMR Scoping > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Mutating Monolithic server.moduleGraph or Invoking Deprecated ssrLoadModule Across Heterogeneous Runtimes ## System Constraints You are a Principal Architect enforcing strict Vite 6 Environment API invariants. Vite 6 decouples execution targets into distinct DevEnvironments with dedicated ModuleRunners and module graphs. Mandate complete runtime boundary separation between client, server, and edge environments, prohibiting deprecated SSR APIs and cross-runtime graph bleeding. ## Strict Guidelines - Engineers MUST ALWAYS configure distinct environments using Vite 6 `environments` configuration options (`client`, `ssr`, or custom targets such as `workerd` or `edge`). - Engineers MUST NOT invoke deprecated legacy APIs such as `server.ssrLoadModule`, `server.ssrTransform`, `server.ssrFixStacktrace`, or global `server.moduleGraph` in Vite 6 projects. - Engineers MUST interact with specific target environments via `server.environments[name]` and evaluate code exclusively through `ModuleRunner` or environment-scoped runner instances. - HMR events MUST ALWAYS be scoped to their target environment using `environment.hot.send()` rather than broadcasting indiscriminately across the global `server.hot.send()` channel. - Custom plugins modifying the transform pipeline MUST inspect `this.environment.name` to prevent executing runtime-incompatible AST transformations or injecting platform-specific intrinsics (e.g., Node.js built-ins into edge runtimes). - Module graph invalidations MUST target `environment.moduleGraph.invalidateModule()` scoped to the affected environment to prevent cascading cache evictions across unrelated runtimes. ## Bad vs Good Implementations ### Vite 6 Multi-Runtime Server Setup with ModuleRunner and Scoped HMR #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using deprecated `server.ssrLoadModule` bypasses the Vite 6 ModuleRunner architecture, combines discrete runtime module graphs into a single graph, and triggers race conditions when multi-runtime targets (such as client + SSR + edge worker) require independent transform options and transports. ```typescript import { createServer } from 'vite'; const server = await createServer({ server: { middlewareMode: true }, appType: 'custom', }); // Anti-pattern: Using deprecated monolithic SSR API in Vite 6 // Leaks SSR graph and breaks multi-runtime isolation (e.g. Node vs workerd) export async function renderPage(url: string) { const mod = await server.ssrLoadModule('/src/entry-server.ts'); // Anti-pattern: Global HMR broadcast across all runtimes server.hot.send({ type: 'custom', event: 'reload-state', data: { url } }); // Anti-pattern: Accessing global moduleGraph instead of environment-specific graph const node = server.moduleGraph.getModuleById('/src/entry-server.ts'); if (node) { server.moduleGraph.invalidateModule(node); } return mod.render(url); } ``` #### Production Standard (Correct) > **Standard**: Adheres to Vite 6 standards by managing the `ssr` DevEnvironment independently, evaluating modules via `ModuleRunner` with `ESModulesEvaluator`, querying `ssrEnvironment.moduleGraph`, and scoping HMR dispatch directly to `ssrEnvironment.hot`. ```typescript import { createServer } from 'vite'; import { ModuleRunner, ESModulesEvaluator } from 'vite/module-runner'; const server = await createServer({ server: { middlewareMode: true }, appType: 'custom', environments: { ssr: { consumer: 'server', resolve: { externalConditions: ['node'] }, }, }, }); // Invariant: Isolate execution using the dedicated environment and ModuleRunner const ssrEnvironment = server.environments.ssr; if (!ssrEnvironment) { throw new Error('SSR environment is not configured'); } const runner = new ModuleRunner( { root: server.config.root, transport: { invoke: async (payload) => { const response = await ssrEnvironment.handleInvoke(payload); return response; }, }, }, new ESModulesEvaluator() ); export async function renderPage(url: string) { const mod = await runner.import('/src/entry-server.ts'); // Invariant: Emit HMR event exclusively through the target environment channel ssrEnvironment.hot.send({ type: 'custom', event: 'reload-state', data: { url }, }); // Invariant: Invalidate isolated environment module graph const node = ssrEnvironment.moduleGraph.getModuleById('/src/entry-server.ts'); if (node) { ssrEnvironment.moduleGraph.invalidateModule(node); } return mod.render(url); } ```

Architectural Specification & Invariant Rationale

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

Vite 6 Multi-Runtime Environment API Isolation and HMR Scoping defines an industrial-grade behavioral standard for frontend engineering. Vite 6 replaces the monolithic SSR architecture with the Environment API, providing isolated module graphs, runtime evaluators, and HMR communication per target runtime (e.g., client, Node.js SSR, Cloudflare workerd). Developers must strictly isolate runtime configurations, utilize runtime-specific ModuleRunner instances, and avoid cross-runtime module graph mutations or unscoped HMR 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: Mutating Monolithic server.moduleGraph or Invoking Deprecated ssrLoadModule Across Heterogeneous Runtimes 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	Mutating Monolithic server.moduleGraph or Invoking Deprecated ssrLoadModule Across Heterogeneous Runtimes	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 using Vite 6 `environments` configuration options (`client`, `ssr`, or custom targets such as `workerd` or `edge`).

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.