Vite 6 Environment API Dual-Runtime Isolation Guardrail

--- description: Vite 6 Environment API Dual-Runtime Isolation Guardrail - Enforces strict isolation between Workerd (Edge) and Node.js environments during full-stack SSR compilation using Vite 6's Environment API. Prevents leaking Node.js built-ins, process state, and host-specific globals into edge isolates while guaranteeing deterministic module resolution boundaries. globs: vite.config.{ts,js,mjs}, src/**/*.{ts,tsx,js,jsx}, server/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-environment-dual-runtime-boundary" --- # Vite 6 Environment API Dual-Runtime Isolation Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Node.js runtime primitives and ambient process state into Workerd edge SSR execution contexts. ## System Constraints You are a Principal Software Architect enforcing the Vite 6 Environment API Dual-Runtime Boundary Standard. You must mandate zero leakage of Node.js globals (process, Buffer, crypto, fs) into edge/workerd target modules, require explicit dual-runtime Vite 6 environment declarations, enforce distinct conditionNames (`workerd` vs `node`), and require platform abstraction layers across runtime boundaries. ## Strict Guidelines - Engineers MUST ALWAYS configure explicit named environments in Vite 6 (`ssr` targeting `workerd` and `node` targeting host processes) using the `environments` top-level configuration key. - Engineers MUST NEVER access ambient `process.env` or Node.js host built-ins (`node:fs`, `node:path`, `node:crypto`) directly within edge-targeted environment execution graphs. - Code targeting edge execution contexts MUST resolve dependencies strictly through runtime-agnostic Web Standard APIs (`fetch`, `Request`, `Response`, `SubtleCrypto`, `ReadableStream`). - Services sharing logic across Node.js build pipelines and edge SSR workers MUST utilize runtime-specific exports defined in `package.json` (`workerd` vs `node` conditions) or structural dependency injection. - Components and server entrypoints NEVER assume ambient global availability; runtime contextual dependencies MUST be passed down explicitly through `AppEnvironmentContext` or Worker invocation bindings. ## Bad vs Good Implementations ### Vite 6 Environment Configuration (Anti-Pattern vs Strict Dual-Runtime Invariant) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Legacy SSR configuration leaks Node-specific host compilation assumptions into edge runtimes, lacks fine-grained per-environment conditionNames, and pollutes global module scopes. ```typescript import { defineConfig } from 'vite'; // ANTI-PATTERN: Vite 5 legacy SSR configuration forcing a single host-runtime assumption. // Module resolution does not differentiate between Edge (Workerd) and Node.js. export default defineConfig({ ssr: { target: 'webworker', noExternal: true, }, define: { 'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV), }, }); ``` #### Production Standard (Correct) > **Standard**: Vite 6 Environment API configures an isolated 'edgeSsr' target with explicit workerd resolution conditions, disabling implicit Node compatibility and keeping edge compilation clean. ```typescript import { defineConfig } from 'vite'; import { workerdEnvironment } from 'vite-environment-workerd'; // INVARIANT: Explicit Vite 6 Dual-Runtime Environment Configuration export default defineConfig({ environments: { client: { consumer: 'client', build: { outDir: 'dist/client' }, }, edgeSsr: { consumer: 'server', resolve: { conditions: ['workerd', 'worker', 'browser'], externalConditions: ['workerd'], noExternal: true, }, nodeCompat: false, build: { outDir: 'dist/edge', ssr: true, rollupOptions: { input: 'src/entry.edge.ts', }, }, }, }, }); ``` ### Cross-Runtime Storage Provider (Ambient Leak vs Explicit Driver Injection) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly importing 'node:fs/promises' will fail compilation or crash at runtime inside a Workerd edge isolate, even when guarded by dynamic branching. ```typescript import fs from 'node:fs/promises'; // ANTI-PATTERN: Hard-coded host file-system dependency inside universal SSR route handler. export async function getConfiguration(key: string): Promise<string> { if (typeof process !== 'undefined' && process.env.EDGE_RUNTIME) { return (globalThis as Record<string, any>)[key]; } return await fs.readFile(`/etc/secrets/${key}`, 'utf-8'); } ``` #### Production Standard (Correct) > **Standard**: Decouples runtime concerns via structural interface injection. Edge runtimes never import Node built-ins, and bindings are provided explicitly at the boundary. ```typescript export interface ConfigurationDriver { get(key: string): Promise<string | null>; } // Edge-safe driver using Web Standards and injected bindings export class EdgeWorkerDriver implements ConfigurationDriver { constructor(private readonly env: Record<string, string | undefined>) {} async get(key: string): Promise<string | null> { return this.env[key] ?? null; } } // Universal consumer agnostic of underlying runtime infrastructure export async function resolveSecret( key: string, driver: ConfigurationDriver ): Promise<string> { const secret = await driver.get(key); if (!secret) { throw new Error(`Missing secret binding for key: ${key}`); } return secret; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Dual-Runtime Isolation Guardrail

Vite 6 Environment API Dual-Runtime Isolation Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation between Workerd (Edge) and Node.js environments during full-stack SSR compilation using Vite 6's Environment API. Prevents leaking Node.js built-ins, process state, and host-specific globals into edge isolates while guaranteeing deterministic module resolution boundaries. 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 Node.js runtime primitives and ambient process state into Workerd edge SSR execution contexts. 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 Node.js runtime primitives and ambient process state into Workerd edge SSR execution contexts.	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 explicit named environments in Vite 6 (`ssr` targeting `workerd` and `node` targeting host processes) using the `environments` top-level configuration key.

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.