Vite 6 Environment API: Multi-Runtime SSR State and Module Context Isolation

--- description: Vite 6 Environment API: Multi-Runtime SSR State and Module Context Isolation - Enforces strict isolation boundaries across Client, Node.js, and Edge/Workerd environments within Vite 6 multi-runtime setups. Prevents cross-environment module graph pollution, ambient global mutations, and shared memory leakage across asynchronous request contexts during unified SSR compilation and execution. globs: vite.config.{ts,js,mjs}, src/**/*.{ts,tsx}, server/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite-6-environment-api-ssr-context-isolation" --- # Vite 6 Environment API: Multi-Runtime SSR State and Module Context Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Module Singletons and Unisolated Cross-Runtime Module Graphs in Vite 6 SSR ## System Constraints You are a Principal Software Architect enforcing Vite 6 Environment API best practices and strict runtime context isolation. You must ensure that applications utilizing Vite 6's multi-environment architecture (client, ssr, edge, workerd) do not cross-contaminate runtime globals, leak module-level singletons across request contexts, or mix incompatible runtime built-ins across distinct target environments. ## Strict Guidelines - Engineers MUST configure distinct environments explicitly in `vite.config.ts` using `environments.<name>` with environment-specific `resolve.conditions`, `resolve.external`, and dedicated `consumer` targets. - Engineers MUST NOT share top-level mutable module variables across requests; all request-scoped state MUST be bound to execution context tokens or explicit context primitives (e.g., `AsyncLocalStorage` in Node or execution context passes in Workerd). - Code targeting Edge or Workerd environments MUST NOT import Node.js built-ins (`node:fs`, `node:path`) unless polyfilled via runtime-specific plugins or targeted condition overrides. - Custom Vite plugins MUST use `this.environment` rather than inspecting global server-wide flags to access the active runtime's module graph and transform configuration. - Server entrypoints MUST NOT assign environment-specific primitives to `globalThis` in shared code paths, preventing runtime pollution across parallel-executed environment runners. ## Bad vs Good Implementations ### Vite 6 Multi-Runtime Environment Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to leverage Vite 6's Environment API, forcing a single SSR target that causes Node and Workerd/Edge dependencies to collide in a single module graph, risking runtime crashes and leaked host globals. ```typescript import { defineConfig } from 'vite'; // ANTI-PATTERN: Monolithic SSR config conflating Node and Edge runtimes export default defineConfig({ ssr: { target: 'node', noExternal: true, }, build: { ssr: 'src/entry-server.ts', }, }); ``` #### Production Standard (Correct) > **Standard**: Defines isolated module graphs and distinct resolution conditions for client, Node SSR, and Edge SSR, ensuring environment-specific dependencies remain strictly segregated. ```typescript import { defineConfig } from 'vite'; // PRODUCTION FIX: Explicit Vite 6 isolated environments with custom conditions export default defineConfig({ environments: { client: { consumer: 'client', build: { outDir: 'dist/client', }, }, ssrNode: { consumer: 'server', resolve: { conditions: ['node', 'import'], external: ['node:async_hooks'], }, build: { outDir: 'dist/server/node', }, }, ssrEdge: { consumer: 'server', resolve: { conditions: ['worker', 'workerd', 'browser'], noExternal: true, }, build: { outDir: 'dist/server/edge', }, }, }, }); ``` ### Request Context Scoping Across Runtimes #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Module-level global state leaks across concurrent asynchronous SSR renders in persistent runtimes (both Node and Workerd), exposing sensitive multi-tenant data. ```typescript // ANTI-PATTERN: Module-level shared mutable state across SSR requests let currentRequestContext: { userId?: string; tenantId?: string } = {}; export function setContext(userId: string, tenantId: string) { currentRequestContext = { userId, tenantId }; } export function handleRender() { // Leaks state between concurrent requests across multi-threaded or async SSR environments return `<div>Tenant: ${currentRequestContext.tenantId}</div>`; } ``` #### Production Standard (Correct) > **Standard**: Uses immutable, explicitly passed request context objects that cannot leak across runtime isolation boundaries, preserving multi-tenant safety across Node, Edge, and Worker environments. ```typescript export interface RequestContext { readonly userId: string; readonly tenantId: string; } // PRODUCTION FIX: Explicit context injection without ambient module pollution export function handleRender(context: RequestContext): string { return `<div>Tenant: ${encodeURIComponent(context.tenantId)}</div>`; } export async function createHandler( request: Request, renderer: (ctx: RequestContext) => string ): Promise<Response> { const context: RequestContext = Object.freeze({ userId: request.headers.get('x-user-id') ?? 'anonymous', tenantId: request.headers.get('x-tenant-id') ?? 'default', }); const html = renderer(context); return new Response(html, { headers: { 'Content-Type': 'text/html' }, }); } ```

Architectural Specification & Invariant Rationale

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

Vite 6 Environment API: Multi-Runtime SSR State and Module Context Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation boundaries across Client, Node.js, and Edge/Workerd environments within Vite 6 multi-runtime setups. Prevents cross-environment module graph pollution, ambient global mutations, and shared memory leakage across asynchronous request contexts during unified SSR compilation and execution. 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: Global Module Singletons and Unisolated Cross-Runtime Module Graphs in Vite 6 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	Global Module Singletons and Unisolated Cross-Runtime Module Graphs in Vite 6 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 configure distinct environments explicitly in `vite.config.ts` using `environments.<name>` with environment-specific `resolve.conditions`, `resolve.external`, and dedicated `consumer` targets.

Engineers MUST configure distinct environments explicitly in `vite.config.ts` using `environments.<name>` with environment-specific `resolve.conditions`, `resolve.external`, and dedicated `consumer` targets.

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.