Vite 6 Environment API: Strict Boundary Isolation for Multi-Runtime SSR

--- description: Vite 6 Environment API: Strict Boundary Isolation for Multi-Runtime SSR - Enforces architectural boundary separation and module graph isolation across simultaneous edge, browser, and server runtime environments using the Vite 6 Environment API. Eliminates runtime leakage, dual-package hazard, and polluted module evaluation by mandating environment-specific module runners, explicit resolution conditions, and target-bound plugin pipelines. globs: vite.config.{ts,js,mjs}, server/**/*.{ts,js}, src/**/*.{ts,tsx,js,jsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-environment-api-multi-runtime-ssr-boundary-isolation" --- # Vite 6 Environment API: Strict Boundary Isolation for Multi-Runtime SSR > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Shared Dev Server State Contamination & Unscoped SSR Module Resolution ## System Constraints You are a Principal Software Architect enforcing Vite 6 Environment API invariants. Multi-runtime SSR pipelines that concurrently execute browser client hydration, edge runtimes (e.g., Cloudflare Workerd, Vercel Edge), and Node.js server pipelines must maintain absolute module isolation. You must prohibit legacy Vite SSR paradigms like un-scoped `server.ssrLoadModule`, prevent runtime-specific primitive leakage (e.g., `node:fs` in Edge or DOM APIs in Node SSR), enforce Vite 6 `createServerModuleRunner` or environment runner abstractions, and mandate granular conditional exports for each distinct environment. ## Strict Guidelines - Engineers MUST configure distinct runtime boundaries via `environments.<name>` in `vite.config.ts` rather than relying on legacy top-level `ssr` configurations. - Engineers MUST NOT invoke deprecated `server.ssrLoadModule()` in multi-runtime setups; all server execution must use `server.environments[envName].runner.import()` or `createServerModuleRunner(server.environments[envName])`. - Vite plugins targeting specific runtime phases MUST inspect `this.environment.name` or implement `applyToEnvironment(env)` to prevent client transforms from executing in server or edge pipelines. - Edge environments (e.g., Workerd) MUST define explicit resolve conditions (`workerd`, `worker`, `edge-light`) and MUST NOT fall back to standard Node.js module resolution. - Shared cross-runtime utilities MUST NOT import runtime-exclusive built-ins (such as `node:path`, `node:fs`, `window`, or `document`) without isolated dynamic imports or conditional exports in `package.json`. - HMR boundaries MUST be isolated per environment: an HMR invalidation in the edge worker runtime module graph must not trigger a full client re-render unless explicitly connected via environment HMR transport channels. ## Bad vs Good Implementations ### Vite 6 Multi-Runtime Environment Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Global SSR configuration causes module graph collision. Specifying both 'workerd' and 'node' in a single global resolve condition causes non-deterministic module selection, and legacy ssr properties cannot isolate edge worker executions from Node SSR. ```typescript import { defineConfig } from 'vite'; // ANTI-PATTERN: Using Vite 5 legacy SSR configuration for a multi-runtime system // Node and Edge targets conflict, leaking Node primitives into Edge workers export default defineConfig({ ssr: { target: 'node', noExternal: true, }, resolve: { conditions: ['workerd', 'node'], // Ambiguous resolution conditions across environments }, }); ``` #### Production Standard (Correct) > **Standard**: Separating targets into distinct Vite 6 environments ('client', 'edge', 'ssr') ensures that each environment possesses its own module graph, resolve conditions, and externalization rules, preventing runtime cross-contamination. ```typescript import { defineConfig } from 'vite'; // PRODUCTION FIX: Explicit Vite 6 Environment API definitions export default defineConfig({ environments: { client: { consumer: 'client', resolve: { conditions: ['browser'], }, }, edge: { consumer: 'server', resolve: { conditions: ['workerd', 'worker'], noExternal: true, }, }, ssr: { consumer: 'server', resolve: { conditions: ['node'], external: ['@prisma/client'], }, }, }, }); ``` ### Dev Server Execution via Vite 6 Module Runner #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: vite.ssrLoadModule lacks isolation context for multi-runtime configurations, cannot execute edge-specific bindings, and bypasses the decoupled ModuleRunner architecture introduced in Vite 6. ```typescript import { createServer } from 'vite'; // ANTI-PATTERN: Executing SSR entry point via deprecated ssrLoadModule async function handleRequest(url: string) { const vite = await createServer(); // ssrLoadModule evaluates against a single generic SSR environment without runtime isolation const { render } = await vite.ssrLoadModule('/src/entry-server.ts'); return render(url); } ``` #### Production Standard (Correct) > **Standard**: createServerModuleRunner coupled with vite.environments.edge guarantees that imported modules are processed through the edge environment's dedicated plugin transforms and resolution conditions. ```typescript import { createServer } from 'vite'; import { createServerModuleRunner } from 'vite/module-runner'; // PRODUCTION FIX: Scoped Vite 6 Environment Module Runner async function handleEdgeRequest(url: string) { const vite = await createServer(); const edgeEnvironment = vite.environments.edge; if (!edgeEnvironment) { throw new Error('Edge environment not configured in Vite server'); } // Instantiate ModuleRunner bound strictly to the edge environment module graph const runner = createServerModuleRunner(edgeEnvironment); const { render } = await runner.import('/src/entry-edge.ts'); return render(url); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API: Strict Boundary Isolation for Multi-Runtime SSR

Vite 6 Environment API: Strict Boundary Isolation for Multi-Runtime SSR defines an industrial-grade behavioral standard for frontend engineering. Enforces architectural boundary separation and module graph isolation across simultaneous edge, browser, and server runtime environments using the Vite 6 Environment API. Eliminates runtime leakage, dual-package hazard, and polluted module evaluation by mandating environment-specific module runners, explicit resolution conditions, and target-bound plugin pipelines. 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: Shared Dev Server State Contamination & Unscoped SSR Module Resolution 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	Shared Dev Server State Contamination & Unscoped SSR Module Resolution	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 configure distinct runtime boundaries via `environments.<name>` in `vite.config.ts` rather than relying on legacy top-level `ssr` configurations.

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.