Vite 6 Environment API Multi-Runtime SSR Boundary Standard

--- description: Vite 6 Environment API Multi-Runtime SSR Boundary Standard - Enforces strict module execution isolation, decoupled module graphs, and runtime-targeted resolve conditions across heterogeneous SSR environments (Node.js, Bun, Workerd) using Vite 6 Environment API. Prevents cross-runtime symbol contamination, node global leakage into edge runtimes, and obsolete legacy ssrLoadModule invocation patterns. globs: vite.config.{ts,js,mjs}, src/server/**/*.{ts,js}, src/entry*.{ts,tsx,js,jsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-environment-api-multi-runtime-ssr-guardrail" --- # Vite 6 Environment API Multi-Runtime SSR Boundary Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Monolithic SSR Module Graphs and Legacy ssrLoadModule Bleeding Cross-Runtime Dependencies ## System Constraints You are a Principal Software Architect enforcing Vite 6 Environment API Multi-Runtime SSR boundaries. You must prohibit legacy Vite SSR paradigms (e.g., single-runtime server.ssrLoadModule, unpartitioned module graphs) and require explicit environment configurations under `environments` with targeted resolve conditions, isolated dev runners, and runtime-specific transform plugins for Node.js, Bun, and Workerd runtimes. ## Strict Guidelines - Engineers MUST ALWAYS configure distinct runtimes using Vite 6 `environments` (e.g., `environments.client`, `environments.ssr`, `environments.workerd`) rather than top-level monolithic `ssr` options. - Engineers MUST NOT invoke deprecated `server.ssrLoadModule()` or `server.ssrFixStacktrace()`; invoke `server.environments[name].runner.executeId()` or `server.environments[name].fetchModule()` instead. - Engineers MUST explicitly partition `resolve.conditions` per environment to prevent leaking Node-specific primitives (`node:fs`, `node:path`) into isolated runtime targets like `workerd`. - Code MUST NEVER share stateful server context or singletons across heterogeneous environment module graphs inside the Vite dev server. - Plugins targeting environment-specific transformations MUST specify `applyToEnvironment(environment)` or check `this.environment.name` instead of inspecting global `ssr` boolean flags. ## Bad vs Good Implementations ### Vite Config Environment Boundary Partitioning #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Configuring SSR via the top-level legacy `ssr` property mixes Node and Worker resolve conditions across the entire pipeline, risking native binary leakage or polyfill failure in edge runtimes like Workerd. ```typescript import { defineConfig } from 'vite'; // ANTI-PATTERN: Monolithic SSR config sharing a single resolution graph export default defineConfig({ ssr: { target: 'webworker', noExternal: true, }, resolve: { // Node conditions mixed with webworker conditions conditions: ['node', 'worker', 'import'], }, }); ``` #### Production Standard (Correct) > **Standard**: Explicitly decouples environments using Vite 6 `environments`, binding specific resolve conditions (`workerd` vs `node`) to avoid cross-runtime symbol contamination and isolated module graphs. ```typescript import { defineConfig } from 'vite'; // PRODUCTION INVARIANT: Vite 6 isolated Environment API partitioning export default defineConfig({ environments: { client: { consumer: 'client', build: { outDir: 'dist/client' }, }, ssr: { consumer: 'server', resolve: { conditions: ['node', 'import', 'default'], externalConditions: ['node'], }, build: { outDir: 'dist/server' }, }, workerd: { consumer: 'server', resolve: { conditions: ['workerd', 'worker', 'browser'], externalConditions: ['workerd', 'worker'], noExternal: true, }, build: { outDir: 'dist/edge' }, }, }, }); ``` ### Dev Server Runtime Execution and Module Loading #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Invoking `server.ssrLoadModule()` forces code execution into the default Node.js host process, completely disregarding runtime-specific isolation constraints configured for alternative runtimes. ```typescript import type { ViteDevServer } from 'vite'; // ANTI-PATTERN: Using deprecated server.ssrLoadModule in Vite 6 multi-runtime context export async function handleRequest(server: ViteDevServer, url: string) { const entry = await server.ssrLoadModule('/src/entry-edge.ts'); return entry.render(url); } ``` #### Production Standard (Correct) > **Standard**: Directly references the isolated `server.environments[runtime].runner`, guaranteeing that the module is compiled and executed strictly within the targeted environment's isolated module graph. ```typescript import type { ViteDevServer } from 'vite'; // PRODUCTION INVARIANT: Target-specific environment runner invocation export async function handleRequest(server: ViteDevServer, url: string, runtime: 'ssr' | 'workerd') { const env = server.environments[runtime]; if (!env) { throw new Error(`Target environment '${runtime}' is not initialized in Vite.`); } // Execute module isolated strictly to the target environment runner/graph const entry = await env.runner.executeId('/src/entry-' + runtime + '.ts'); return entry.render(url); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Multi-Runtime SSR Boundary Standard

Vite 6 Environment API Multi-Runtime SSR Boundary Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict module execution isolation, decoupled module graphs, and runtime-targeted resolve conditions across heterogeneous SSR environments (Node.js, Bun, Workerd) using Vite 6 Environment API. Prevents cross-runtime symbol contamination, node global leakage into edge runtimes, and obsolete legacy ssrLoadModule invocation patterns. 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: Monolithic SSR Module Graphs and Legacy ssrLoadModule Bleeding Cross-Runtime Dependencies 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	Monolithic SSR Module Graphs and Legacy ssrLoadModule Bleeding Cross-Runtime Dependencies	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 runtimes using Vite 6 `environments` (e.g., `environments.client`, `environments.ssr`, `environments.workerd`) rather than top-level monolithic `ssr` options.

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.