Vite 6 Environment API Runtime Module Isolation and Secret Boundary Standard

--- description: Vite 6 Environment API Runtime Module Isolation and Secret Boundary Standard - Enforces strict runtime module graph boundaries across client, server, and edge environments using Vite 6's Environment API. Eliminates credential leakage by invalidating shared module caches and barring server-only dependencies from traversing into client compilation passes. Guarantees immutable separation between WebWorker, Node.js, and browser execution contexts during dev HMR and multi-environment builds. globs: vite.config.ts, vite.config.mts, src/**/*.{ts,tsx,js,jsx}, server/**/*.{ts,js}, edge/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-environment-api-runtime-module-isolation-standard" --- # Vite 6 Environment API Runtime Module Isolation and Secret Boundary Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Implicit Cross-Environment Imports and Shared Module Cache Infiltration Leaking Server Secrets into Client Bundles ## System Constraints You are a Principal Software Architect enforcing Vite 6 Environment API Runtime Module Isolation. You must prevent accidental module sharing, shared global states across environment boundaries, and secret leaks caused by importing server or edge modules into client compilation targets. Mandate strict environment configurations using Vite 6 environments definitions, ban isomorphic dynamic imports containing secure runtime code, and require explicit environment plugin barriers. ## Strict Guidelines - Engineers MUST ALWAYS declare isolated runtime environments explicitly using Vite 6 `builder.environments` and `environments` configuration options for `client`, `ssr`, and `edge` targets. - Engineers MUST NOT rely on client-side conditional runtime checks (such as `if (typeof window === 'undefined')`) to guard server-only secrets or private infrastructure tokens. - Code MUST use explicit module subpath export patterns (e.g., `import 'server-only'`) or Vite 6 environment-conditioned resolution to invalidate cross-boundary imports at resolve time. - Services MUST isolate HMR module invalidations per environment using Vite 6 `DevEnvironment.hot` channels without crossing environment boundaries. - Plugins MUST target specific environments via `applyToEnvironment(environment)` or the `hotUpdate` environment hook rather than executing globally across all module graphs. - Components NEVER import services, database clients, or environment-variable wrappers that load un-prefixed (non-`VITE_`) server variables. ## Bad vs Good Implementations ### Cross-Boundary Leak via Isomorphic Resolver vs Vite 6 Strict Environment Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using universal bundles and compile-time 'define' or conditional window checks permits bundler tree-shaking failures. The client bundle graph still processes the AST node, potentially retaining process.env.DB_PASSWORD in client artifacts and causing severe credential leakage. ```typescript // vite.config.ts import { defineConfig } from 'vite'; export default defineConfig({ // Flawed: Single module graph shared across SSR and Client // Allows accidental barrel imports of server secrets into client assets define: { 'process.env.DB_PASSWORD': JSON.stringify(process.env.DB_PASSWORD) }, ssr: { noExternal: ['shared-lib'] } }); // src/lib/api.ts // Leaks process.env.DB_PASSWORD into the client bundle through shared chunking export const fetchUserData = async () => { if (typeof window === 'undefined') { return fetch('/api', { headers: { Auth: process.env.DB_PASSWORD } }); } return fetch('/api'); }; ``` #### Production Standard (Correct) > **Standard**: Configures discrete runtime module graphs using Vite 6 Environment API. The custom plugin inspects `this.environment.name` during resolution, deterministically halting compilation if server-only dependencies attempt entry into the client environment graph. ```typescript // vite.config.ts import { defineConfig } from 'vite'; export default defineConfig({ // Vite 6 Environment API: Explicit isolated runtimes environments: { client: { build: { outDir: 'dist/client', rollupOptions: { input: './src/entry-client.tsx' } } }, ssr: { build: { outDir: 'dist/server', rollupOptions: { input: './src/entry-server.tsx' } } } }, plugins: [ { name: 'enforce-environment-boundary', resolveId(id, importer, options) { // Vite 6 exposes options.ssr or target environment context const isClient = this.environment?.name === 'client'; if (isClient && (id.includes('.server') || id === 'node:fs')) { throw new Error(`Security Violation: Module ${id} cannot be resolved in '${this.environment.name}' environment (imported by ${importer})`); } return null; } } ] }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Runtime Module Isolation and Secret Boundary Standard

Vite 6 Environment API Runtime Module Isolation and Secret Boundary Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict runtime module graph boundaries across client, server, and edge environments using Vite 6's Environment API. Eliminates credential leakage by invalidating shared module caches and barring server-only dependencies from traversing into client compilation passes. Guarantees immutable separation between WebWorker, Node.js, and browser execution contexts during dev HMR and multi-environment builds. 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: Implicit Cross-Environment Imports and Shared Module Cache Infiltration Leaking Server Secrets into 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	Implicit Cross-Environment Imports and Shared Module Cache Infiltration Leaking Server Secrets into 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 isolated runtime environments explicitly using Vite 6 `builder.environments` and `environments` configuration options for `client`, `ssr`, and `edge` targets.

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.