Vite 6 Environment API Multi-Runtime SSR Sandboxing Standard

--- description: Vite 6 Environment API Multi-Runtime SSR Sandboxing Standard - Mandates strict module graph isolation and runtime sandboxing across heterogeneous targets (Node.js, Bun, Edge/Workerd) using Vite 6's Environment API. Prohibits global pollution and legacy monolithic ssrLoadModule execution patterns that cause cross-runtime leakage during SSR compilation and evaluation. globs: vite.config.{ts,js,mjs}, src/**/*.{ts,tsx}, server/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-environment-api-ssr-sandboxing" --- # Vite 6 Environment API Multi-Runtime SSR Sandboxing Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Host Node.js Globals and Sharing Monolithic Module Graphs Across Heterogeneous SSR Runtimes ## System Constraints You are a Principal Software Architect enforcing Vite 6 Environment API multi-runtime SSR sandboxing standards. Mandate strict environment segregation in full-stack build matrices. Forbid deprecated Vite 5 SSR APIs (such as server.ssrLoadModule), ensure plugins read this.environment context rather than deprecated options.ssr flags, and mandate sandboxed ModuleRunner instances for non-Node.js evaluation targets (e.g., Cloudflare Workerd, Deno, Bun). ## Strict Guidelines - Engineers MUST ALWAYS configure discrete execution targets using the top-level 'environments' configuration matrix in vite.config.ts rather than relying on global SSR flags. - Engineers MUST NOT invoke legacy 'server.ssrLoadModule()' or 'server.ssrFixStacktrace()'; all SSR module imports must run through 'server.environments[target].runner.import()' or dedicated ModuleRunner instances. - Plugins MUST inspect 'this.environment' within hook contexts (e.g., resolveId, load, transform) instead of inspecting the deprecated boolean 'options?.ssr' flag. - Module runners evaluating WinterCG or Edge runtime targets MUST execute within sandboxed context boundaries, ensuring Node.js native built-ins (e.g., node:fs, node:crypto) and global mutations do not pollute worker environments. - Components and server modules NEVER pollute globalThis with runtime-specific singletons; cross-boundary state must be scoped explicitly via request context or runtime-provided environment bindings. ## Bad vs Good Implementations ### Configuring Heterogeneous SSR Environments with Vite 6 #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Legacy Vite 5 patterns use a monolithic server.ssrLoadModule call that unconditionally runs in Node.js, polluting the shared module graph and preventing distinct compilation/runtime conditions for Edge workers or non-Node environments. ```typescript import { defineConfig, ViteDevServer } from 'vite'; // ANTI-PATTERN: Monolithic SSR configuration sharing single module graph export default defineConfig({ build: { ssr: 'src/entry-server.ts', }, ssr: { // Pollutes edge runtime builds with Node.js external resolution external: ['node:path'], }, }); export async function handleDevRequest(server: ViteDevServer, url: string) { // Deprecated: Uses single Node.js runtime runner, failing edge workers const { render } = await server.ssrLoadModule('/src/entry-server.ts'); return render(url); } ``` #### Production Standard (Correct) > **Standard**: The Vite 6 Environment API isolates 'nodeSsr' and 'edgeSsr' environments with explicit resolution conditions and outDir destinations. It executes code via server.environments.edgeSsr.runner.import(), preventing cross-runtime pollution. ```typescript import { defineConfig } from 'vite'; import type { ViteDevServer } from 'vite'; // PRODUCTION FIX: Discrete Vite 6 Environment API multi-runtime definitions export default defineConfig({ environments: { client: { consumer: 'client', build: { outDir: 'dist/client' }, }, nodeSsr: { consumer: 'server', resolve: { conditions: ['node'] }, build: { outDir: 'dist/server' }, }, edgeSsr: { consumer: 'server', resolve: { conditions: ['worker', 'webworker', 'workerd'], noExternal: true, }, build: { outDir: 'dist/edge', target: 'esnext', }, }, }, }); export async function handleEdgeRequest(server: ViteDevServer, url: string) { // Access sandboxed module runner for the explicit edge environment const edgeEnv = server.environments.edgeSsr; if (!edgeEnv) { throw new Error('Edge SSR environment not initialized.'); } const { render } = await edgeEnv.runner.import('/src/entry-edge.ts'); return render(url); } ``` ### Environment-Aware Plugin Context #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using options?.ssr treats SSR as a monolith, making it impossible to differentiate between Node.js, Bun, and Edge worker environments within plugins. ```typescript import type { Plugin } from 'vite'; // ANTI-PATTERN: Relying on deprecated ssr boolean flag inside plugin hooks export function crossRuntimePlugin(): Plugin { return { name: 'cross-runtime-plugin', resolveId(id, _importer, options) { if (options?.ssr) { // Blindly assumes SSR is always Node.js return id.includes('virtual:node-only') ? id : null; } return null; }, }; } ``` #### Production Standard (Correct) > **Standard**: Accessing this.environment inside plugin hooks allows fine-grained routing and compile-time validation specific to the actively targeted environment. ```typescript import type { Plugin } from 'vite'; // PRODUCTION FIX: Scoping plugin behavior via this.environment context export function crossRuntimePlugin(): Plugin { return { name: 'cross-runtime-plugin', resolveId(id) { const env = this.environment; if (!env) { return null; } if (env.name === 'edgeSsr') { if (id.startsWith('node:')) { throw new Error(`Forbidden Node.js builtin "${id}" imported in edge environment.`); } return id === 'virtual:env-config' ? '\0virtual:env-config:edge' : null; } if (env.name === 'nodeSsr') { return id === 'virtual:env-config' ? '\0virtual:env-config:node' : null; } return null; }, }; } ```

Architectural Specification & Invariant Rationale

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

Vite 6 Environment API Multi-Runtime SSR Sandboxing Standard defines an industrial-grade behavioral standard for frontend engineering. Mandates strict module graph isolation and runtime sandboxing across heterogeneous targets (Node.js, Bun, Edge/Workerd) using Vite 6's Environment API. Prohibits global pollution and legacy monolithic ssrLoadModule execution patterns that cause cross-runtime leakage during SSR compilation and evaluation. 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 Host Node.js Globals and Sharing Monolithic Module Graphs Across Heterogeneous SSR 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	Leaking Host Node.js Globals and Sharing Monolithic Module Graphs Across Heterogeneous SSR 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 discrete execution targets using the top-level 'environments' configuration matrix in vite.config.ts rather than relying on global SSR flags.

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.