Vite 6 Multi-Environment Isolation and Cross-Runtime Boundary Enforcement

--- description: Vite 6 Multi-Environment Isolation and Cross-Runtime Boundary Enforcement - Vite 6 Environment API allows distinct execution contexts (Node SSR, Workerd edge, React Server Components, and client bundles) to run in unified dev and build pipelines. In multi-runtime setups, you must enforce strict module boundary isolation, dedicated DevEnvironment configs, and explicit runtime export conditions to prevent host Node.js globals and stateful module graphs from cross-pollinating isolated runtimes. globs: vite.config.{ts,js,mjs}, src/**/*.{ts,tsx}, server/**/*.{ts,js} 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-503" --- # Vite 6 Multi-Environment Isolation and Cross-Runtime Boundary Enforcement > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Pollinating Node.js Globals and Sharing Module Execution Caches Across Isolated Vite 6 Environments ## System Constraints You are a Principal Software Architect enforcing strict module boundary isolation and runtime guarantees using the Vite 6 Environment API. You must mandate discrete environment definitions for heterogeneous execution contexts (e.g., client, ssr running in Node, edge running in Workerd/Miniflare). Ensure that host Node built-ins, shared memory singletons, and unisolated module graphs never leak between client, Node, and edge worker environments. ## Strict Guidelines - Engineers MUST ALWAYS configure runtime-specific conditions inside discrete `environments.<name>.resolve.conditions` rather than relying on top-level `resolve.conditions`. - Engineers MUST NOT invoke deprecated `server.ssrLoadModule` or `server.ssrFixStacktrace`; migrate exclusively to `server.environments[name].runner.import()` or `fetchModule()` depending on whether the target environment is a `RunnableDevEnvironment` or `FetchableDevEnvironment`. - Code executing inside edge/Workerd environments MUST NOT import Node.js core APIs (`node:fs`, `node:child_process`, `node:os`) unless specifically provided by the runtime's compatibility flags. - Services running in heterogeneous environments MUST NOT access `process.env` directly; access configuration via explicit runtime injection (e.g., `import.meta.env` or Cloudflare `env` binding context passed through the environment dispatcher). - Module singletons (e.g., in-memory caches, database clients) MUST NEVER be imported across environment boundaries; communicate strictly via serializable RPCs, HTTP, or custom WebSocket dispatch channels. - Build pipelines MUST explicitly invoke `builder.build(builder.environments[name])` per environment target instead of running monolithic client/server builds that conflate asset resolution graphs. ## Bad vs Good Implementations ### Vite 6 Multi-Environment Configuration with Node and Workerd Runtime Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Global definitions of 'conditions' and 'ssr.target' break module isolation across different targets. Workerd-targeted modules resolve Node conditions, while Node server modules attempt to execute with webworker constraints. Module caches and globals cross-contaminate between client, worker, and Node processes. ```typescript import { defineConfig } from 'vite'; // ANTI-PATTERN: Vite 5 legacy pattern conflating edge and node runtimes // into a single generic SSR target, causing cross-runtime leaks export default defineConfig({ ssr: { target: 'webworker', // Overrides SSR globally; breaks Node.js SSR services noExternal: true, }, resolve: { // Host-polluting conditions applied globally across client and worker conditions: ['workerd', 'worker', 'node'], }, server: { // Deprecated Vite 5 hook allowing Node globals to leak into worker runner middlewareMode: true, } }); ``` #### Production Standard (Correct) > **Standard**: Declaring distinct environments ('client', 'ssrNode', 'edgeWorker') establishes segregated module graphs, dedicated module runners, and strict runtime condition resolution. Edge builds will fail fast if attempting to import Node-specific modules, while Node builds preserve full platform compatibility. ```typescript import { defineConfig } from 'vite'; // PRODUCTION PATTERN: Vite 6 Environment API with strict per-runtime isolation export default defineConfig({ environments: { client: { consumer: 'client', build: { outDir: 'dist/client', }, }, ssrNode: { consumer: 'server', resolve: { conditions: ['node'], externalConditions: ['node'], }, build: { outDir: 'dist/server/node', }, }, edgeWorker: { consumer: 'server', resolve: { conditions: ['workerd', 'worker', 'browser'], externalConditions: ['workerd', 'worker'], }, build: { outDir: 'dist/server/edge', }, }, }, builder: { async buildApp(builder) { // Execute builds sequentially or in parallel without graph interference await builder.build(builder.environments.client); await builder.build(builder.environments.ssrNode); await builder.build(builder.environments.edgeWorker); }, }, }); ``` ### Executing Isolated Server-Side Code via Vite 6 DevEnvironment Runner #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using 'server.ssrLoadModule' bypasses environment boundaries and loads edge code directly into the Vite host Node.js process. Native Node APIs will silently pass in development and immediately crash in the target runtime (e.g. Cloudflare Workers). ```typescript import type { ViteDevServer } from 'vite'; // ANTI-PATTERN: Using deprecated ssrLoadModule executes code on host Node runner // even if the module is intended for a Workerd isolate export async function handleRequest(server: ViteDevServer, url: string) { const mod = await server.ssrLoadModule('/src/edge-entry.ts'); // process.env and Node globals are implicitly accessible here, masking edge runtime failures return mod.default.fetch(new Request(url)); } ``` #### Production Standard (Correct) > **Standard**: Targeting the specific `RunnableDevEnvironment` guarantees execution within that environment's isolated module graph and runner context. Any attempted access to foreign runtime globals will fail deterministically during local development. ```typescript import type { ViteDevServer } from 'vite'; import type { RunnableDevEnvironment } from 'vite'; // PRODUCTION PATTERN: Dispatching execution strictly to the designated DevEnvironment export async function handleRequest(server: ViteDevServer, url: string, runtime: 'ssrNode' | 'edgeWorker') { const targetEnv = server.environments[runtime]; if (!targetEnv) { throw new Error(`Environment [${runtime}] is not configured in Vite server.`); } // Enforce runner interface for runnable environments (e.g., Node / Worker isolate runner) const runnable = targetEnv as RunnableDevEnvironment; const mod = await runnable.runner.import('/src/entry.ts'); return mod.default.fetch(new Request(url)); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Multi-Environment Isolation and Cross-Runtime Boundary Enforcement

Vite 6 Multi-Environment Isolation and Cross-Runtime Boundary Enforcement defines an industrial-grade behavioral standard for frontend engineering. Vite 6 Environment API allows distinct execution contexts (Node SSR, Workerd edge, React Server Components, and client bundles) to run in unified dev and build pipelines. In multi-runtime setups, you must enforce strict module boundary isolation, dedicated DevEnvironment configs, and explicit runtime export conditions to prevent host Node.js globals and stateful module graphs from cross-pollinating isolated runtimes. 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-Pollinating Node.js Globals and Sharing Module Execution Caches Across Isolated Vite 6 Environments 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-Pollinating Node.js Globals and Sharing Module Execution Caches Across Isolated Vite 6 Environments	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 runtime-specific conditions inside discrete `environments.<name>.resolve.conditions` rather than relying on top-level `resolve.conditions`.

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.