Strict Isolation of Client, Server, and Edge Runtime Environments in Vite 6

--- description: Strict Isolation of Client, Server, and Edge Runtime Environments in Vite 6 - Enforces strict runtime module isolation using the Vite 6 Environment API across client, SSR node, and edge runtimes. Prevents cross-environment module graph leakage, prototype pollution, and execution of server secrets in client bundles during development HMR and production compilation. globs: vite.config.ts, vite.config.*.ts, src/entry-client.ts, src/entry-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-isolated-runtime-boundary" --- # Strict Isolation of Client, Server, and Edge Runtime Environments in Vite 6 > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Environment Module Graph Leakage and Unbound Shared State via Legacy ssrLoadModule ## System Constraints You are a Principal Software Architect enforcing runtime boundary invariants via the Vite 6 Environment API. You must mandate strict separation between client, ssr, and custom worker/edge module graphs. Reject legacy Vite 5 dual-graph patterns, global ssrLoadModule calls, shared module-level state across runtimes, and leaking server secrets into client-targeted ASTs. Enforce explicit Environment instances, custom ModuleNode boundary validation, and independent HMR transport channels. ## Strict Guidelines - Engineers MUST ALWAYS declare isolated runtime environments explicitly using the Vite 6 `environments` configuration block (e.g., `client`, `ssr`, `edge`) instead of legacy top-level `ssr` overrides. - Engineers MUST ALWAYS access environment-specific runners via `server.environments[name].runner` rather than legacy untyped `server.ssrLoadModule`. - Engineers MUST NOT share in-memory singleton module state or mutate prototypes across environment boundaries; every environment must instantiate isolated module instances. - Code MUST use explicit import condition attributes and Vite environment transforms to prevent edge/server module references from entering the client module graph. - Plugins MUST target explicit environments via `applyToEnvironment(environment)` or the `perEnvironmentStartEndDuringDev` lifecycle hooks to prevent cross-runtime pollution. - Components and server handlers NEVER import raw configuration objects containing environment secrets without explicitly passing them through an isolated runtime bridge. ## Bad vs Good Implementations ### Configuring Strict Environment API Boundaries vs Legacy Ambiguous SSR #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Legacy configurations allow module nodes and cache references to be shared between client and SSR contexts during development, creating prototype pollution and accidental leakage of server-only modules into the client graph. ```typescript import { defineConfig } from 'vite'; // ANTI-PATTERN: Vite 5 legacy config collapses client and server transforms into implicit shared state, // leading to shared module graph node leakage and unisolated SSR runners export default defineConfig({ build: { ssr: true, outDir: 'dist/server' }, ssr: { noExternal: ['shared-lib'], target: 'node' } }); ``` #### Production Standard (Correct) > **Standard**: The Vite 6 `environments` API establishes distinct `DevEnvironment` instances with isolated resolve conditions, AST transformations, and target runners, preventing cross-environment module leaking. ```typescript import { defineConfig } from 'vite'; // PRODUCTION INVARIANT: Vite 6 isolated environment declarations // Completely partitions the module graph, transform options, and runtimes export default defineConfig({ environments: { client: { build: { outDir: 'dist/client' }, dev: { createEnvironment(name, config) { // Client runs in native browser runtime return undefined; } } }, ssr: { build: { outDir: 'dist/server' }, resolve: { conditions: ['node', 'import'] }, consumer: 'server' } } }); ``` ### Dev Server Execution via Environment Runner vs ssrLoadModule #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Vite 5 `server.ssrLoadModule` is deprecated and operates without a strict boundary context. It executes directly in the main dev server Node process, polluting global scope and breaking edge-runtime simulation. ```typescript import type { ViteDevServer } from 'vite'; // ANTI-PATTERN: ssrLoadModule operates on a monolithic dev server graph export async function handleRequest(server: ViteDevServer, url: string) { // Leaks Node globals and modules into global cache without runtime encapsulation const { render } = await server.ssrLoadModule('/src/entry-server.ts'); return render(url); } ``` #### Production Standard (Correct) > **Standard**: Using `server.environments[name].runner.import` ensures execution occurs strictly within the designated environment runner scope, honoring environment-specific transforms and module isolation. ```typescript import type { ViteDevServer } from 'vite'; // PRODUCTION INVARIANT: Environment API isolated runner boundary export async function handleRequest(server: ViteDevServer, url: string) { const ssrEnvironment = server.environments.ssr; if (!ssrEnvironment) { throw new Error('SSR Environment not configured on Vite dev server'); } // Isolated evaluation within the dedicated EnvironmentRunner const entryModule = await ssrEnvironment.runner.import('/src/entry-server.ts'); return entryModule.render(url); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Strict Isolation of Client, Server, and Edge Runtime Environments in Vite 6

Strict Isolation of Client, Server, and Edge Runtime Environments in Vite 6 defines an industrial-grade behavioral standard for frontend engineering. Enforces strict runtime module isolation using the Vite 6 Environment API across client, SSR node, and edge runtimes. Prevents cross-environment module graph leakage, prototype pollution, and execution of server secrets in client bundles during development HMR and production compilation. 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-Environment Module Graph Leakage and Unbound Shared State via Legacy ssrLoadModule 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-Environment Module Graph Leakage and Unbound Shared State via Legacy ssrLoadModule	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 the Vite 6 `environments` configuration block (e.g., `client`, `ssr`, `edge`) instead of legacy top-level `ssr` overrides.

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.