Vite 6 Environment API Multi-Runtime Module Segregation Standard

--- description: Vite 6 Environment API Multi-Runtime Module Segregation Standard - Enforces strict module evaluation boundaries and environment isolation across Node.js, workerd, and edge runtimes in Vite 6 multi-environment setups. Prevents ambient Node globals, un-isolated Vite transform pipelines, and shared module graphs from leaking platform-specific capabilities across heterogeneous execution contexts. globs: vite.config.{ts,js,mjs}, src/server/**/*.{ts,js}, src/worker/**/*.{ts,js}, src/entry*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-environment-api-runtime-segregation-standard" --- # Vite 6 Environment API Multi-Runtime Module Segregation Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Runtime Global Leakage and Shared Module Graph Contamination in Heterogeneous Vite 6 Environments ## System Constraints You are a Principal Software Architect enforcing the Vite 6 Environment API Multi-Runtime Module Segregation Standard. Your primary responsibility is to guarantee that distinct execution targets (client, node SSR, workerd/Cloudflare edge) within the same Vite dev server operate under completely segregated Environment instances with isolated ModuleGraph, EnvironmentRunner, and resolve conditions. Prevent accidental cross-runtime ambient API leakage (e.g., node:fs imported in workerd or edge Web APIs accessed in Node without polyfills) and disallow shared monolithic plugin pipelines across mismatched runtimes. ## Strict Guidelines - Engineers MUST ALWAYS configure distinct environments using `environments` in Vite 6 configuration rather than multiplexing single SSR flags. - Engineers MUST explicitly define environment-specific `resolve.conditions` (e.g., `['workerd', 'worker']` vs `['node']`) to prevent importing incompatible platform entrypoints. - Engineers MUST instantiate dedicated `FetchableDevEnvironment` or `DevEnvironment` runtimes with isolated `ModuleGraph` instances for each heterogeneous target. - Engineers MUST NOT rely on ambient Node.js globals (`process`, `Buffer`, `__dirname`) inside workerd or browser worker environment target trees. - Plugins MUST target specific environments via `applyToEnvironment(environment)` or inspect `this.environment.name` instead of applying universal transform logic. - Code interacting with environment-specific capabilities MUST be bounded behind module-level dynamic import barriers or explicit build condition exports. ## Bad vs Good Implementations ### Vite 6 Multi-Environment Configuration Segregation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Multiplexing runtimes inside a single Vite 5 legacy SSR configuration forces workerd and Node.js targets to share resolution conditions. This causes Node-only packages to leak into the edge bundle or resolve edge-shimmed modules in Node SSR, causing runtime crashes and broken hot-module replacement (HMR). ```typescript import { defineConfig } from 'vite'; // Anti-pattern: Shared single SSR configuration multiplexing Node and Workerd export default defineConfig({ ssr: { target: 'webworker', noExternal: true, }, resolve: { // Single resolve condition array shared across edge and node conditions: ['workerd', 'node', 'import'], }, }); ``` #### Production Standard (Correct) > **Standard**: Defines isolated Vite 6 runtime environments with independent resolution conditions and build pipelines. The edge runtime is guaranteed to resolve 'workerd' conditions and avoid Node-native dependencies, maintaining strict isolation across the entire module graph. ```typescript import { defineConfig } from 'vite'; // Production standard: Vite 6 Environment API with dedicated runtime isolation export default defineConfig({ environments: { ssr: { resolve: { conditions: ['node'], externalConditions: ['node'], }, consumer: 'server', }, edge: { resolve: { conditions: ['workerd', 'worker'], externalConditions: ['workerd', 'worker'], noExternal: true, }, consumer: 'server', }, }, builder: { buildApp: async (builder) => { await builder.build(builder.environments.ssr); await builder.build(builder.environments.edge); }, }, }); ``` ### Environment-Aware Plugin Scoping #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The transform hook executes unconditionally across both Node and workerd SSR environments. Injecting node:buffer into an entrypoint intended for edge environments will fail resolution or cause workerd runner initialization to crash. ```typescript import type { Plugin } from 'vite'; // Anti-pattern: Universal transform plugin executing across all environments blindly export function injectRuntimePolyfill(): Plugin { return { name: 'runtime-polyfill', transform(code, id) { if (id.includes('entry-server')) { // Injects Node global without checking target runtime environment return `import 'node:buffer';\n${code}`; } }, }; } ``` #### Production Standard (Correct) > **Standard**: Leverages Vite 6 `applyToEnvironment` hook and `this.environment.name` introspection to constrain transforms strictly to the Node environment, preventing ambient node globals from leaking into the edge runtime. ```typescript import type { Plugin } from 'vite'; // Production standard: Environment-aware Vite 6 plugin with explicit boundary export function injectRuntimePolyfill(): Plugin { return { name: 'runtime-polyfill', applyToEnvironment(environment) { // Only execute this plugin inside the dedicated Node SSR environment return environment.name === 'ssr'; }, transform(code, id) { if (this.environment.name === 'ssr' && id.includes('entry-server')) { return { code: `import { Buffer } from 'node:buffer';\nglobalThis.Buffer = Buffer;\n${code}`, map: null, }; } }, }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Multi-Runtime Module Segregation Standard

Vite 6 Environment API Multi-Runtime Module Segregation Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict module evaluation boundaries and environment isolation across Node.js, workerd, and edge runtimes in Vite 6 multi-environment setups. Prevents ambient Node globals, un-isolated Vite transform pipelines, and shared module graphs from leaking platform-specific capabilities across heterogeneous execution contexts. 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-Runtime Global Leakage and Shared Module Graph Contamination in Heterogeneous 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-Runtime Global Leakage and Shared Module Graph Contamination in Heterogeneous 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 distinct environments using `environments` in Vite 6 configuration rather than multiplexing single 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.