Vite 6 Environment API Cross-Runtime State Isolation & Module Graph Guardrail

--- description: Vite 6 Environment API Cross-Runtime State Isolation & Module Graph Guardrail - Enforces strict module graph separation across client, SSR, and Edge runtimes leveraging the Vite 6 Environment API. Prevents runtime state pollution, server-side secret leaks via client module graph inclusion, and invalid node built-in resolution in edge and browser environments. globs: vite.config.ts, vite.config.*.ts, 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-api-runtime-isolation-vite-6-environme-508" --- # Vite 6 Environment API Cross-Runtime State Isolation & Module Graph Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Boundary Module Graph Leakage & Runtime Contamination via Shared Bundler Contexts ## System Constraints You are a Principal Software Architect enforcing zero-leakage runtime isolation under Vite 6. You must mandate strict multi-environment boundaries using Vite 6's Environment API (`builder.environments` / `server.environments`). Under no circumstances may client-side bundles import or resolve modules from server/edge environments, or share module graph node instances across execution runtimes. ## Strict Guidelines - Engineers MUST ALWAYS configure explicit, isolated runtime environments (`client`, `ssr`, and optionally `edge` or custom targets) using Vite 6's top-level `environments` configuration block. - Engineers MUST NEVER access `process.env` directly in code resolved within the `client` environment module graph; client code MUST strictly consume validated `import.meta.env` properties prefixed with `VITE_`. - Vite plugins MUST NEVER share in-memory state or cache transform results across distinct environment instances; plugins interacting with environment-specific transforms must inspect `this.environment` within plugin hooks. - Server-side code and SSR entry points MUST NOT import modules marked with client-only directives or modules that trigger browser global accesses without dynamic boundary wrappers. - Build pipelines MUST ALWAYS compile separate target manifests per environment using `builder.build(builder.environments[envName])` to ensure deterministic chunk isolation. ## Bad vs Good Implementations ### Vite 6 Environment Configuration Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Defines SSR and client targets within a shared compilation pass, accidentally leaking sensitive compile-time definitions (DATABASE_URL) into the shared AST resolution and causing client/server module graph entanglement. ```typescript import { defineConfig } from 'vite'; // Anti-pattern: Monolithic config sharing plugins and resolution across SSR and Client export default defineConfig({ ssr: { noExternal: ['shared-lib'], }, define: { 'process.env.DATABASE_URL': JSON.stringify(process.env.DATABASE_URL), }, build: { rollupOptions: { input: { client: './src/entry-client.tsx', server: './src/entry-server.tsx', }, }, }, }); ``` #### Production Standard (Correct) > **Standard**: Configures Vite 6 first-class runtime environments (`client` and `ssr`). Each environment maintains completely disjoint module graphs, transforms, and rollup output settings, preventing secret leakage and invalid polyfill cross-contamination. ```typescript import { defineConfig } from 'vite'; // Production invariant: Explicit Vite 6 Environment API with dedicated isolated module graphs export default defineConfig({ environments: { client: { build: { outDir: 'dist/client', rollupOptions: { input: './src/entry-client.tsx', }, }, }, ssr: { build: { outDir: 'dist/server', rollupOptions: { input: './src/entry-server.tsx', }, }, resolve: { noExternal: ['shared-lib'], }, }, }, builder: { buildApp: async (builder) => { await builder.build(builder.environments.client); await builder.build(builder.environments.ssr); }, }, }); ``` ### Environment-Aware Plugin Hook Implementation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: A single module cache (`resolvedModules`) is shared across both client and server compilations. An ID resolved in the client graph can prematurely suppress or taint resolution in the SSR graph. ```typescript import type { Plugin } from 'vite'; // Anti-pattern: Shared state across environment instances inside plugin export function leakProneEnvPlugin(): Plugin { const resolvedModules = new Set<string>(); return { name: 'leak-prone-plugin', resolveId(id) { if (resolvedModules.has(id)) { return null; } resolvedModules.add(id); return null; }, }; } ``` #### Production Standard (Correct) > **Standard**: Leverages Vite 6 `this.environment.name` context within plugin hooks to ensure isolation guarantees are strictly validated per target environment. ```typescript import type { Plugin } from 'vite'; // Production invariant: Vite 6 Environment API aware transform/resolution hooks export function isolatedEnvPlugin(): Plugin { return { name: 'isolated-env-plugin', resolveId: { order: 'pre', handler(id) { // this.environment isolates state per active compilation target ('client' | 'ssr') if (this.environment.name === 'client' && id.startsWith('node:')) { throw new Error(`Refusing to resolve Node built-in "${id}" in client environment.`); } return null; }, }, }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Cross-Runtime State Isolation & Module Graph Guardrail

Vite 6 Environment API Cross-Runtime State Isolation & Module Graph Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces strict module graph separation across client, SSR, and Edge runtimes leveraging the Vite 6 Environment API. Prevents runtime state pollution, server-side secret leaks via client module graph inclusion, and invalid node built-in resolution in edge and browser environments. 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-Boundary Module Graph Leakage & Runtime Contamination via Shared Bundler 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	Cross-Boundary Module Graph Leakage & Runtime Contamination via Shared Bundler 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, isolated runtime environments (`client`, `ssr`, and optionally `edge` or custom targets) using Vite 6's top-level `environments` configuration block.

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.