Vite 6 Environment API: Strict Multi-Runtime Module Boundary Isolation

--- description: Vite 6 Environment API: Strict Multi-Runtime Module Boundary Isolation - Enforces strict runtime module isolation using Vite 6 Environment API across Client, Node.js, and Workerd compilation targets. Eliminates server-side secret exposure, platform-specific polyfill contamination, and native runtime module leakage into browser asset graphs through dedicated environment pipelines and conditional resolution. globs: vite.config.ts, vite.config.*.ts, src/**/*.{ts,tsx,js,jsx}, package.json alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-multiruntime-environment-boundary-isolation" --- # Vite 6 Environment API: Strict Multi-Runtime Module Boundary Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Monolithic Multi-Target Vite Configurations Leaking Server Secrets and Node Runtimes into Browser Bundles ## System Constraints You are a Principal Software Architect enforcing Vite 6 Environment API boundaries. You must reject legacy monolithic SSR configs that conflate client, Node.js, and Workerd targets. Enforce explicit `environments` declarations, strict runtime condition mapping, and complete isolation between server secrets and client graphs. ## Strict Guidelines - Engineers MUST configure distinct compilation environments via the Vite 6 top-level `environments` configuration object instead of relying on legacy binary `build.ssr` flags. - Engineers MUST NOT import platform-specific runtime modules (e.g., `node:fs`, `node:crypto`, `cloudflare:workers`) within modules accessible to the `client` environment graph. - Vite configurations MUST define isolated `resolve.conditions` per environment target (e.g., `['browser']` for client, `['workerd', 'worker']` for edge workers, and `['node']` for SSR services). - Shared libraries consumed across multiple environments MUST enforce runtime boundaries using `package.json` conditional exports (`browser`, `workerd`, `node`, `default`) rather than unified barrels. - Engineers MUST explicitly set `build.rollupOptions.output` or environment-specific external assertions to immediately fail compilation if server-only dependencies enter the `client` compilation pipeline. - Components NEVER import server actions, edge context accessors, or database credentials directly into client-rendered leaf nodes or hydratable islands. ## Bad vs Good Implementations ### Vite 6 Multi-Runtime Environment Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: A monolithic Vite config shares resolve conditions across targets. When the client build runs, 'workerd' and 'node' conditions cause edge/server polyfills and sensitive defines to leak into browser bundles. ```typescript import { defineConfig } from 'vite'; // ANTI-PATTERN: Monolithic configuration with shared resolve/build pipelines // leaking Workerd bindings and Node polyfills into client bundles export default defineConfig({ resolve: { // Unified conditions blend runtime targets conditions: ['workerd', 'worker', 'browser', 'node'], }, ssr: { // Flawed binary toggle: cannot isolate Workerd edge from Node tooling noExternal: true, }, define: { 'process.env.API_SECRET': JSON.stringify(process.env.API_SECRET), }, }); ``` #### Production Standard (Correct) > **Standard**: Explicit environment targets ('client', 'ssr', 'edge') isolate resolve conditions and externals, preventing server APIs or polyfills from being resolved in the client compilation graph. ```typescript import { defineConfig } from 'vite'; // PRODUCTION INVARIANT: Vite 6 Environment API with dedicated runtime pipelines export default defineConfig({ environments: { client: { build: { outDir: 'dist/client', }, resolve: { conditions: ['browser'], noExternal: false, }, }, ssr: { build: { outDir: 'dist/server', }, resolve: { conditions: ['node'], external: [/^node:/], }, }, edge: { build: { outDir: 'dist/edge', }, resolve: { conditions: ['workerd', 'worker'], external: [/^cloudflare:/], }, }, }, }); ``` ### Cross-Runtime Package Consumption and Boundary Enforcement #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Static imports of `node:crypto` are traversed during client bundling regardless of the `typeof window` runtime check, triggering bundle failures or pulling massive polyfills into the browser. ```typescript // src/shared/crypto.ts // ANTI-PATTERN: Runtime branching inside module body allows bundler to package both branches import nodeCrypto from 'node:crypto'; export function hashToken(token: string): string { if (typeof window === 'undefined') { return nodeCrypto.createHash('sha256').update(token).digest('hex'); } throw new Error('hashToken is server-only'); } ``` #### Production Standard (Correct) > **Standard**: Splitting implementations across conditional entrypoints resolves the correct platform binary at compile-time via Vite 6 Environment conditions, avoiding dead-code inclusion and node polyfill leaks. ```typescript // src/shared/crypto.browser.ts export async function hashToken(token: string): Promise<string> { const msgUint8 = new TextEncoder().encode(token); const hashBuffer = await crypto.subtle.digest('SHA-256', msgUint8); return Array.from(new Uint8Array(hashBuffer)) .map(b => b.toString(16).padStart(2, '0')) .join(''); } // src/shared/crypto.node.ts import { createHash } from 'node:crypto'; export function hashToken(token: string): string { return createHash('sha256').update(token).digest('hex'); } // package.json conditional exports ensure zero cross-contamination: // "exports": { // ".": { // "browser": "./src/shared/crypto.browser.ts", // "node": "./src/shared/crypto.node.ts" // } // } ```

Architectural Specification & Invariant Rationale

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

Vite 6 Environment API: Strict Multi-Runtime Module Boundary Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict runtime module isolation using Vite 6 Environment API across Client, Node.js, and Workerd compilation targets. Eliminates server-side secret exposure, platform-specific polyfill contamination, and native runtime module leakage into browser asset graphs through dedicated environment pipelines and conditional resolution. 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: Monolithic Multi-Target Vite Configurations Leaking Server Secrets and Node Runtimes into Browser Bundles 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	Monolithic Multi-Target Vite Configurations Leaking Server Secrets and Node Runtimes into Browser Bundles	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 compilation environments via the Vite 6 top-level `environments` configuration object instead of relying on legacy binary `build.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.