Vite 6 Environment API Multi-Runtime SSR Module Graph Isolation

--- description: Vite 6 Environment API Multi-Runtime SSR Module Graph Isolation - Enforces strict module graph and runtime isolation using the Vite 6 Environment API across heterogeneous deployment targets (browser, Node.js, and Edge/workerd). Prevents non-deterministic module resolution, runtime global pollution, and cross-runtime cache poisoning during unified full-stack compilation. globs: vite.config.{ts,js,mjs}, src/**/*.{ts,tsx,js,jsx}, server/**/*.{ts,js,mjs} 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-environme-276" --- # Vite 6 Environment API Multi-Runtime SSR Module Graph Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-contaminating runtime globals and unpartitioned module graphs via legacy monolithic Vite SSR APIs. ## System Constraints You are a Principal Software Architect enforcing Vite 6 Environment API standards. Vite 6 deprecates legacy single-context SSR pipelines (`server.ssrLoadModule`, monolithic `server.moduleGraph`) in favor of partitioned `DevEnvironment` instances with isolated module graphs, transform pipelines, and export conditions. You must mandate strict environment isolation between client, Node.js, and edge workers to prevent cross-runtime global pollution and improper package resolution. ## Strict Guidelines - Engineers MUST ALWAYS declare explicit `environments` in `vite.config.ts` (e.g., `client`, `ssr`, `edge`) rather than relying on legacy monolithic SSR options. - Engineers MUST configure runtime-specific `resolve.conditions` and `resolve.externalConditions` uniquely within each environment configuration to avoid condition leakage across execution contexts. - Engineers MUST NOT access `server.moduleGraph` or `server.ssrLoadModule` directly; code MUST invoke the target environment instance directly via `server.environments[name].runner.import()` or `server.environments[name].moduleGraph`. - Code executing in Edge environments (e.g., Cloudflare Workers, workerd) MUST NEVER import Node.js built-ins or mutate global runtime singletons shared with the Node.js SSR pipeline. - Plugins MUST implement environment-aware hooks (`resolveId`, `load`, `transform`) by checking `this.environment.name` rather than inspecting global booleans like `options.ssr`. - Components and libraries targeting multi-runtime SSR MUST gate environment-specific imports behind conditional export maps or explicit dynamic imports evaluated by the corresponding environment runner. ## Bad vs Good Implementations ### Vite 6 Config: Declarative Multi-Runtime Environment Separation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring global conditions like 'workerd' alongside 'node' in a monolithic config causes Vite to resolve edge-incompatible Node packages for edge builds or vice versa, and forces both runtimes to share a single module resolution context. ```typescript import { defineConfig } from 'vite'; // ANTI-PATTERN: Monolithic SSR configuration leaking Node.js conditions into Edge export default defineConfig({ ssr: { noExternal: true, target: 'node', }, resolve: { // Condition leakage across browser, node, and edge runtimes conditions: ['workerd', 'node', 'import'], }, }); ``` #### Production Standard (Correct) > **Standard**: Defines isolated environment pipelines with explicit consumers and target-specific resolve conditions, ensuring module graphs and dependency resolutions remain strictly segregated. ```typescript import { defineConfig } from 'vite'; // PRODUCTION INVARIANT: Vite 6 Environment API with dedicated isolated environments export default defineConfig({ environments: { client: { consumer: 'client', resolve: { conditions: ['browser', 'import'], }, }, ssr: { consumer: 'server', resolve: { conditions: ['node', 'import'], externalConditions: ['node'], }, }, edge: { consumer: 'server', resolve: { conditions: ['workerd', 'worker', 'import'], externalConditions: ['workerd'], }, }, }, }); ``` ### Server Orchestration: Accessing Isolated Environment Run Time #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: server.ssrLoadModule uses legacy unpartitioned resolution, risking cross-contamination of module state between client/edge/node executions. ```typescript import { createServer } from 'vite'; async function handleRequest(url: string) { const server = await createServer(); // ANTI-PATTERN: Deprecated legacy API shares module cache across runtimes const { render } = await server.ssrLoadModule('/src/entry-server.ts'); return render(url); } ``` #### Production Standard (Correct) > **Standard**: Interacts directly with Vite 6 `DevEnvironment.runner`, ensuring that evaluation context, module transforms, and runtime conditions are bound exclusively to the designated target environment. ```typescript import { createServer, type ViteDevServer } from 'vite'; async function handleRequest(server: ViteDevServer, url: string, isEdgeRuntime: boolean) { // PRODUCTION INVARIANT: Route directly to the isolated Environment runner const envName = isEdgeRuntime ? 'edge' : 'ssr'; const targetEnv = server.environments[envName]; if (!targetEnv) { throw new Error(`Environment '${envName}' is not configured on Vite server.`); } // Execute isolated module resolution within the environment's dedicated runner const { render } = await targetEnv.runner.import('/src/entry-server.ts'); return render(url); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Multi-Runtime SSR Module Graph Isolation

Vite 6 Environment API Multi-Runtime SSR Module Graph Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict module graph and runtime isolation using the Vite 6 Environment API across heterogeneous deployment targets (browser, Node.js, and Edge/workerd). Prevents non-deterministic module resolution, runtime global pollution, and cross-runtime cache poisoning during unified full-stack compilation. 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-contaminating runtime globals and unpartitioned module graphs via legacy monolithic Vite SSR APIs. 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-contaminating runtime globals and unpartitioned module graphs via legacy monolithic Vite SSR APIs.	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 declare explicit `environments` in `vite.config.ts` (e.g., `client`, `ssr`, `edge`) rather than relying on legacy 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.