Vite 6 Environment API Runtime Scope Fencing and Realm Isolation

--- description: Vite 6 Environment API Runtime Scope Fencing and Realm Isolation - Enforces strict module execution graph isolation and condition boundaries across distinct client, server (Node.js), and edge runtime realms using Vite 6 Environment API. Prevents silent SSR secret exfiltration, invalid cross-realm tree-shaking, and global pollution caused by deprecated ssrLoadModule invocation and shared module runners. globs: vite.config.ts, vite.config.*.ts, src/entry-server.ts, src/entry-client.ts, server.ts, src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-environment-api-runtime-scope-fencing" --- # Vite 6 Environment API Runtime Scope Fencing and Realm Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking SSR secrets and cross-realm globals via legacy ssrLoadModule and unfenced Vite environment graphs ## System Constraints You are a Principal Software Architect enforcing Vite 6 Environment API Runtime Scope Fencing. Mandate strict boundary isolation between client, ssr, and worker execution graphs. Ensure zero secret leakage from server to client environments, require explicit environment-aware plugin filtering, and prohibit deprecated monolithic SSR runners. ## Strict Guidelines - Engineers MUST ALWAYS configure distinct environments (e.g., 'client', 'ssr', 'edge') within `environments` configuration block in Vite 6, never relying on implicit global defaults. - Engineers MUST NOT invoke deprecated `server.ssrLoadModule()` or legacy `server.ssrFixStacktrace()`; module loading MUST be delegated to environment-scoped module runners via `server.environments[name].runner.import()` or `server.environments[name].moduleGraph`. - Plugins MUST filter transformations using `this.environment.name` or configure `applyToEnvironment(environment)` to prevent server-only transform plugins from executing over client bundles or leaking server-only AST injections. - Resolve conditions MUST be strictly fenced per environment: the client environment MUST NOT specify `node` or server export conditions, and the ssr/edge environment MUST isolate target runtimes (`workerd`, `node`, `edge-light`). - Components and shared utilities NEVER directly import server configuration files, environment secrets (`process.env.PRIVATE_*`), or node built-ins without an explicit ambient guard or fence module. ## Bad vs Good Implementations ### Configuring Fenced Environments in Vite 6 #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Configuring root-level conditions allows the client module graph to resolve server conditions, creating opportunities for private modules, environment-specific credentials, and Node built-in imports to bleed into the client bundle. ```typescript import { defineConfig } from 'vite'; // ANTI-PATTERN: Unified monolithic SSR setup without Environment API isolation export default defineConfig({ ssr: { noExternal: ['lodash-es', 'server-secrets-pkg'], }, resolve: { // Conditions leak into client resolution, allowing server conditions in browser graph conditions: ['node', 'import', 'module'], }, }); ``` #### Production Standard (Correct) > **Standard**: Explicitly splits client and SSR into first-class Vite 6 DevEnvironments with strictly fenced resolution conditions, ensuring client code cannot resolve node conditions. ```typescript import { defineConfig } from 'vite'; export default defineConfig({ environments: { client: { build: { outDir: 'dist/client', }, resolve: { conditions: ['browser', 'import', 'module'], noExternal: false, }, }, ssr: { build: { outDir: 'dist/server', }, resolve: { conditions: ['node', 'import', 'module'], external: ['node:*'], }, }, }, }); ``` ### Environment-Aware Vite Plugin Implementation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: This plugin transforms modules regardless of environment. When the client module graph requests 'config-provider', secret tokens are compiled directly into client-shipped assets. ```typescript import type { Plugin } from 'vite'; // ANTI-PATTERN: Plugin indiscriminately injects server configurations export function serverConfigPlugin(secretToken: string): Plugin { return { name: 'server-config-injector', transform(code, id) { if (id.includes('config-provider')) { return `${code}; export const SECRET = '${secretToken}';`; } }, }; } ``` #### Production Standard (Correct) > **Standard**: Uses `applyToEnvironment` and runtime checks on `this.environment.name` to guarantee AST mutations containing secrets are only executed within the SSR realm. ```typescript import type { Plugin } from 'vite'; export function serverConfigPlugin(secretToken: string): Plugin { return { name: 'server-config-injector', applyToEnvironment(env) { // Fencing: Only activate for 'ssr' environment, completely detached from 'client' return env.name === 'ssr'; }, transform(code, id) { if (this.environment.name !== 'ssr') { return null; } if (id.includes('config-provider')) { return `${code}; export const SECRET = ${JSON.stringify(secretToken)};`; } }, }; } ``` ### Module Execution via Vite 6 Module Runner vs Deprecated ssrLoadModule #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: ssrLoadModule executes code in the Node main realm with global state leaking across requests and lacks fine-grained runner configurations available in Vite 6. ```typescript import type { ViteDevServer } from 'vite'; // ANTI-PATTERN: Deprecated Vite 5 ssrLoadModule lacks realm and memory isolation export async function handleRequest(server: ViteDevServer, url: string) { const entry = await server.ssrLoadModule('/src/entry-server.tsx'); return entry.render(url); } ``` #### Production Standard (Correct) > **Standard**: Accesses the dedicated ssr DevEnvironment and uses its isolated module runner, preventing cross-environment state pollution and respecting environment-scoped transforms. ```typescript import type { ViteDevServer } from 'vite'; export async function handleRequest(server: ViteDevServer, url: string) { const ssrEnvironment = server.environments.ssr; if (!ssrEnvironment) { throw new Error('SSR Environment is not initialized'); } // Use Vite 6 Module Runner bound explicitly to the SSR environment instance const entry = await ssrEnvironment.runner.import('/src/entry-server.tsx'); return entry.render(url); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Runtime Scope Fencing and Realm Isolation

Vite 6 Environment API Runtime Scope Fencing and Realm Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict module execution graph isolation and condition boundaries across distinct client, server (Node.js), and edge runtime realms using Vite 6 Environment API. Prevents silent SSR secret exfiltration, invalid cross-realm tree-shaking, and global pollution caused by deprecated ssrLoadModule invocation and shared module runners. 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 SSR secrets and cross-realm globals via legacy ssrLoadModule and unfenced Vite environment graphs 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 SSR secrets and cross-realm globals via legacy ssrLoadModule and unfenced Vite environment graphs	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 distinct environments (e.g., 'client', 'ssr', 'edge') within `environments` configuration block in Vite 6, never relying on implicit global defaults.

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.