Vite 6 Environment API Runtime Module Isolation Barrier

--- description: Vite 6 Environment API Runtime Module Isolation Barrier - Enforces strict compile-time and runtime module isolation across heterogeneous Vite 6 environments (client, ssr, edge). Prevents Node.js built-ins, privileged server SDKs, and sensitive server-only variables from leaking into browser or edge module subgraphs during isomorphic full-stack builds. globs: vite.config.{ts,js,mjs}, src/**/*.{ts,tsx,js,jsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-environment-api-runtime-module-isolation-guardrail" --- # Vite 6 Environment API Runtime Module Isolation Barrier > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Server Privileges and Node.js Runtimes into Browser Bundles via Legacy Monolithic SSR Configs ## System Constraints You are a Principal Software Architect enforcing the Vite 6 Environment API Runtime Module Isolation Barrier. You must ensure that Vite 6 application configurations explicitly isolate the 'client', 'ssr', and 'edge' runtime module graphs using the Vite 6 Environment API (`createEnvironment`, `builder.buildApp`, and environment-scoped `resolve.conditions`). You must reject any legacy Vite monolithic SSR configurations that rely on unisolated shared transforms or insecure dual-build flags (`ssrBuild`), which risk leaking Node.js built-in modules (`node:crypto`, `node:fs`) and backend secrets into client-bound JavaScript assets. ## Strict Guidelines - Engineers MUST ALWAYS declare isolated runtime environments using the Vite 6 `environments` configuration block rather than legacy top-level `ssr` build switches. - Engineers MUST NOT allow modules importing Node.js standard library built-ins (`node:*`) or backend database clients into the `client` environment module graph. - Plugins targeting specific runtimes MUST ALWAYS specify the `applyToEnvironment` hook filter or check `this.environment.name` to prevent ambient transform pollution across environment graphs. - Code executing in the client environment MUST NEVER access un-prefixed server secrets or ambient Node.js globals (`process.versions.node`, `process.env.*` beyond designated public manifests). - Services sharing cross-environment isomorphic code MUST use explicit runtime conditional exports or dedicated subpath exports (e.g., `pkg/client` vs `pkg/server`) validated through `resolve.conditions` per environment. ## Bad vs Good Implementations ### Vite Configuration: Legacy Shared SSR Config vs. Vite 6 Isolated Environment API #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Legacy Vite SSR setups rely on process-level switches (`process.env.IS_SSR`) and shared module graphs, which permits server libraries and node dependencies to leak into client transformation graphs when imports are shared across isomorphic boundaries. ```typescript import { defineConfig } from 'vite'; // ANTI-PATTERN: Monolithic SSR configuration sharing resolution // and transforms across browser and server targets without runtime boundaries export default defineConfig({ ssr: { noExternal: ['lodash-es', 'server-secrets-lib'], }, build: { rollupOptions: { input: process.env.IS_SSR ? './src/entry-server.ts' : './src/entry-client.ts', }, }, }); ``` #### Production Standard (Correct) > **Standard**: Vite 6 Environment API enforces strict runtime isolation by segregating module graphs and resolution conditions between `client` and `ssr`. Node.js targets and browser builds are treated as independent runtime units. ```typescript import { defineConfig } from 'vite'; // PRODUCTION INVARIANT: Vite 6 isolated environments with runtime-specific module barriers export default defineConfig({ environments: { client: { build: { outDir: 'dist/client', rollupOptions: { input: './src/entry-client.ts', }, }, resolve: { conditions: ['browser', 'import', 'module'], externalConditions: ['browser'], }, }, ssr: { build: { outDir: 'dist/server', rollupOptions: { input: './src/entry-server.ts', }, }, resolve: { conditions: ['node', 'import', 'module'], externalConditions: ['node'], noExternal: true, }, }, }, builder: { async buildApp(builder) { await builder.build(builder.environments.client); await builder.build(builder.environments.ssr); }, }, }); ``` ### Plugin Boundary: Cross-Environment Leakage vs. Environment-Scoped Hook Filtering #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Failing to gate virtual modules or plugin hooks to specific environments allows backend configurations and environment variables to be consumed by client-side components without build-time errors. ```typescript import type { Plugin } from 'vite'; // ANTI-PATTERN: Plugin blindly intercepts imports across ALL targets without verifying active environment export function serverSecretsPlugin(): Plugin { return { name: 'server-secrets-leak', resolveId(id) { if (id === 'virtual:runtime-config') { return '\0virtual:runtime-config'; } }, load(id) { if (id === '\0virtual:runtime-config') { // Leaks Node server process env to the browser bundle during build return `export const config = ${JSON.stringify(process.env)};`; } }, }; } ``` #### Production Standard (Correct) > **Standard**: Uses Vite 6's `applyToEnvironment` hook and `this.environment.name` runtime check to quarantine server-side virtual modules, throwing a compile-time invariant violation if client environments attempt resolution. ```typescript import type { Plugin } from 'vite'; // PRODUCTION INVARIANT: Use environment-aware hooks and strict isolation barriers export function runtimeConfigPlugin(): Plugin { return { name: 'isolated-runtime-config', // Vite 6 per-environment transform gating applyToEnvironment(environment) { return environment.name === 'ssr'; }, resolveId(id) { if (id === 'virtual:server-runtime-config') { return '\0virtual:server-runtime-config'; } }, load(id) { if (id === '\0virtual:server-runtime-config') { if (this.environment.name !== 'ssr') { this.error(`Forbidden import of 'virtual:server-runtime-config' from environment '${this.environment.name}'.`); } return `export const serverConfig = { dbUrl: process.env.DATABASE_URL };`; } }, }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Runtime Module Isolation Barrier

Vite 6 Environment API Runtime Module Isolation Barrier defines an industrial-grade behavioral standard for frontend engineering. Enforces strict compile-time and runtime module isolation across heterogeneous Vite 6 environments (client, ssr, edge). Prevents Node.js built-ins, privileged server SDKs, and sensitive server-only variables from leaking into browser or edge module subgraphs during isomorphic full-stack 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: Leaking Server Privileges and Node.js Runtimes into Browser Bundles via Legacy Monolithic SSR Configs 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 Server Privileges and Node.js Runtimes into Browser Bundles via Legacy Monolithic SSR Configs	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 using the Vite 6 `environments` configuration block rather than legacy top-level `ssr` build switches.

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.