Vite 6 Environment API Multi-Runtime Boundary Isolation Standard

--- description: Vite 6 Environment API Multi-Runtime Boundary Isolation Standard - Enforces strict compile-time module graph and symbol isolation across distinct runtime targets (client, edge/workerd, and Node SSR) using the Vite 6 Environment API. Prevents fatal runtime crashes and catastrophic security disclosures caused by native Node.js built-ins, private server credentials, or unpolyfilled symbols leaking into browser or edge worker distribution bundles. globs: vite.config.ts, vite.config.*.ts, src/**/*.{ts,tsx,js,jsx} 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-636" --- # Vite 6 Environment API Multi-Runtime Boundary Isolation Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Shared SSR Module Graph Leaking Node Built-ins and Secrets into Edge and Client Bundles ## System Constraints You are a Principal Software Architect enforcing strict multi-runtime boundary isolation using the Vite 6 Environment API. Mandate distinct module graph separation between 'client', 'ssr' (Node.js), and 'edge' (workerd/V8 isolates) environments. Reject any configuration or code pattern that risks cross-runtime symbol contamination or exposes native server-only imports to edge or browser targets. ## Strict Guidelines - Engineers MUST ALWAYS declare explicit environment targets under `environments` in `vite.config.ts` (e.g., `client`, `ssr`, `edge`) instead of relying on legacy monolithic SSR build options. - Engineers MUST NOT import Node.js native modules (`node:fs`, `node:path`, `node:crypto`) or server-only SDKs into modules evaluated within `client` or `edge` Vite environments. - Configurations MUST define independent `resolve.conditions` per environment (e.g., `['workerd', 'worker']` for edge, `['node']` for Node SSR, and `['browser']` for client) to enforce conditional export compliance. - Custom plugins MUST check `this.environment.name` inside `resolveId` and `transform` hooks to prevent server-only transformations from applying to browser or edge environments. - Edge environments MUST set `resolve.noExternal: true` or explicitly inline non-workerd compatible dependencies to prevent invalid dynamic imports at runtime. - Components and routes MUST NEVER import server database connectors or private credentials directly; data fetching across environment boundaries must occur strictly through isolated endpoints or formal RPC contracts. ## Bad vs Good Implementations ### Vite 6 Multi-Runtime Environment Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Configuring multi-runtime targets under a single legacy SSR config causes edge runtimes (such as Cloudflare Workers) to inherit Node.js module resolutions. This results in 'node:fs' and 'pg' being dynamically referenced in environments where native Node bindings do not exist. ```typescript import { defineConfig } from 'vite'; // ANTI-PATTERN: Vite 5 legacy monolithic SSR config without runtime isolation // Node-specific packages and edge workers share the same resolve graph export default defineConfig({ build: { ssr: true, rollupOptions: { input: { server: 'src/entry-server.ts', worker: 'src/entry-worker.ts' } } }, ssr: { // Single blanket external list mixes Node and Edge constraints external: ['node:fs', 'pg'] } }); ``` #### Production Standard (Correct) > **Standard**: Explicit environment configurations guarantee independent module resolution graphs. The 'edge' environment targets 'workerd' conditions with full inlining (`noExternal: true`), while 'ssr' isolates Node.js dependencies, preventing cross-runtime contamination. ```typescript import { defineConfig } from 'vite'; // PRODUCTION INVARIANT: Vite 6 Environment API with strict multi-runtime boundaries export default defineConfig({ environments: { client: { build: { outDir: 'dist/client' } }, edge: { resolve: { conditions: ['workerd', 'worker', 'browser'], noExternal: true }, build: { outDir: 'dist/edge', rollupOptions: { input: 'src/entry-worker.ts' } } }, ssr: { resolve: { conditions: ['node'] }, build: { outDir: 'dist/ssr', rollupOptions: { input: 'src/entry-server.ts' } } } } }); ``` ### Vite 6 Environment-Aware Plugin Boundary Enforcement #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The plugin marks 'server-only' modules and 'node:*' built-ins as external indiscriminately across all environments. When building for the client or edge, this emits external import statements that trigger immediate runtime crashes in browsers and V8 isolate workers. ```typescript import type { Plugin } from 'vite'; // ANTI-PATTERN: Environment-agnostic plugin failing to verify target runtime export function enforceServerGuard(): Plugin { return { name: 'server-guard', resolveId(id) { if (id.startsWith('node:') || id === 'server-only') { // Returns external resolution indiscriminately across client, edge, and node return { id, external: true }; } return null; } }; } ``` #### Production Standard (Correct) > **Standard**: The plugin leverages Vite 6's `this.environment.name` in its `resolveId` hook to abort compilation with an explicit error when server-only or Node-native imports attempt to enter client or edge compilation pipelines. ```typescript import type { Plugin } from 'vite'; // PRODUCTION INVARIANT: Runtime-aware plugin using Vite 6 Environment API hook context export function enforceServerGuard(): Plugin { return { name: 'server-guard', resolveId(id) { const currentEnv = this.environment.name; const isNodeBuiltin = id.startsWith('node:'); if (isNodeBuiltin && currentEnv !== 'ssr') { this.error( `Illegal runtime boundary crossing: '${id}' cannot be resolved in '${currentEnv}' environment.` ); } if (id === 'server-only') { if (currentEnv === 'client' || currentEnv === 'edge') { this.error(`Forbidden import of 'server-only' module in runtime environment '${currentEnv}'.`); } return { id, external: currentEnv === 'ssr' }; } return null; } }; } ```

Architectural Specification & Invariant Rationale

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

Vite 6 Environment API Multi-Runtime Boundary Isolation Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict compile-time module graph and symbol isolation across distinct runtime targets (client, edge/workerd, and Node SSR) using the Vite 6 Environment API. Prevents fatal runtime crashes and catastrophic security disclosures caused by native Node.js built-ins, private server credentials, or unpolyfilled symbols leaking into browser or edge worker distribution bundles. 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 SSR Module Graph Leaking Node Built-ins and Secrets into Edge and Client 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	Shared SSR Module Graph Leaking Node Built-ins and Secrets into Edge and Client 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 ALWAYS declare explicit environment targets under `environments` in `vite.config.ts` (e.g., `client`, `ssr`, `edge`) instead of relying on legacy monolithic SSR build options.

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.