Vite 6 Environment API Multi-Runtime Module Partitioning and State Isolation

--- description: Vite 6 Environment API Multi-Runtime Module Partitioning and State Isolation - Enforces strict runtime module graph partitioning and dedicated execution environments using the Vite 6 Environment API. Prevents cross-environment memory pollution, platform global contamination (e.g., Node.js built-ins in Workerd/Edge runtimes), and split-brain singleton states across Universal SSR targets. globs: vite.config.ts, vite.config.*.ts, src/server/**/*.{ts,tsx}, src/entry.*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-ssr-environment-module-partitioning" --- # Vite 6 Environment API Multi-Runtime Module Partitioning and State Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Monolithic Module Graph Evaluation and Cross-Runtime State Bleed in Multi-Target SSR ## System Constraints You are a Principal Software Architect enforcing architectural boundaries in Vite 6 SSR applications. You must strictly enforce runtime module isolation across heterogeneous SSR environments (e.g., Client, Node.js server, Edge/Workerd workers) using Vite 6's Environment API (`DevEnvironment`, `EnvironmentRunner`, and explicit `environments` configuration). Flag and reject any usage of deprecated single-graph SSR paradigms (such as `viteServer.ssrLoadModule`), cross-environment global object mutation, or unpartitioned condition resolution that causes memory leaks or dual-package hazard. ## Strict Guidelines - Engineers MUST ALWAYS configure distinct environments within `vite.config.ts` via the Vite 6 `environments` object (e.g., `client`, `ssr`, `edge`) with dedicated resolution conditions and runtime runners. - Engineers MUST NOT invoke deprecated `server.ssrLoadModule()` or `server.ssrFixStacktrace()`; evaluate modules strictly through the target environment runner via `server.environments[envName].runner.import()`. - Engineers MUST specify explicit export conditions in `resolve.conditions` per environment (e.g., `['workerd', 'worker']` for edge vs. `['node']` for standard SSR) to avert bundling Node.js native APIs into edge contexts. - Services MUST encapsulate state inside request-scoped contexts (e.g., using `AsyncLocalStorage`) rather than process-level global singletons that leak across parallel SSR evaluation ticks. - Plugins MUST target specific environments using `applyToEnvironment(environment)` or the `perEnvironmentStartEndDuringDev` hook instead of executing universally on the root server context. - Build pipelines MUST invoke Vite 6 multi-environment builds (`builder.build(server.environments.edge)`) separately to emit non-interfering chunk topologies per runtime target. ## Bad vs Good Implementations ### Vite 6 Multi-Runtime Environment Configuration and Execution #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using Vite 5's monolithic `ssrLoadModule` evaluates all server code under the default Node process environment. It prevents running Edge-compatible SSR targets alongside Node services, causes export condition conflicts, and leads to cross-request global singleton leaks. ```typescript import { createServer } from 'vite'; import type { Request, Response } from 'express'; // ANTI-PATTERN: Vite 5 legacy monolithic SSR server // Mixed runtime assumptions, global state bleed, deprecated ssrLoadModule const vite = await createServer({ server: { middlewareMode: true }, appType: 'custom', ssr: { // Single SSR target cannot isolate edge vs node runtime conditions noExternal: true } }); export async function handleRequest(req: Request, res: Response) { // Leaks Node globals into SSR module cache; triggers dual-package hazards // if an edge runtime target is also serviced from this process const { render } = await vite.ssrLoadModule('/src/entry.server.tsx'); const html = await render(req.url); res.status(200).set({ 'Content-Type': 'text/html' }).end(html); } ``` #### Production Standard (Correct) > **Standard**: Configures Vite 6 multi-environment definitions with partitioned resolution conditions. Evaluates server and edge runtimes via discrete `createServerModuleRunner` instances targeting distinct environments, guaranteeing clean module isolation without cross-runtime leaks. ```typescript import { createServer, type ViteDevServer } from 'vite'; import { createServerModuleRunner } from 'vite/module-runner'; // PRODUCTION PATTERN: Vite 6 Environment API with explicit runtime partitioning export const server = await createServer({ environments: { client: { build: { outDir: 'dist/client' } }, ssr: { resolve: { conditions: ['node', 'import'] }, build: { outDir: 'dist/server' } }, edge: { resolve: { conditions: ['workerd', 'worker', 'edge-light'] }, build: { outDir: 'dist/edge' } } } }); export async function handleNodeSsr(url: string, context: Record<string, unknown>): Promise<string> { const ssrEnv = server.environments.ssr; if (!ssrEnv) throw new Error('SSR environment not initialized'); // Explicit module runner bound exclusively to the ssr environment module graph const runner = createServerModuleRunner(ssrEnv); const { render } = await runner.import('/src/entry.node.ts'); return render(url, context); } export async function handleEdgeSsr(url: string, workerEnv: unknown): Promise<Response> { const edgeEnv = server.environments.edge; if (!edgeEnv) throw new Error('Edge environment not initialized'); const runner = createServerModuleRunner(edgeEnv); const { handleWorkerRequest } = await runner.import('/src/entry.edge.ts'); return handleWorkerRequest(url, workerEnv); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Multi-Runtime Module Partitioning and State Isolation

Vite 6 Environment API Multi-Runtime Module Partitioning and State Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict runtime module graph partitioning and dedicated execution environments using the Vite 6 Environment API. Prevents cross-environment memory pollution, platform global contamination (e.g., Node.js built-ins in Workerd/Edge runtimes), and split-brain singleton states across Universal SSR targets. 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: Monolithic Module Graph Evaluation and Cross-Runtime State Bleed in Multi-Target SSR 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	Monolithic Module Graph Evaluation and Cross-Runtime State Bleed in Multi-Target SSR	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 within `vite.config.ts` via the Vite 6 `environments` object (e.g., `client`, `ssr`, `edge`) with dedicated resolution conditions and runtime runners.

Engineers MUST ALWAYS configure distinct environments within `vite.config.ts` via the Vite 6 `environments` object (e.g., `client`, `ssr`, `edge`) with dedicated resolution conditions and runtime runners.

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.