Vite 6 Environment API Multi-Runtime SSR Isolation & Memory Leak Prevention

--- description: Vite 6 Environment API Multi-Runtime SSR Isolation & Memory Leak Prevention - Enforces strict heap separation and lifecycle boundary governance across Vite 6 DevEnvironment instances (e.g., Node.js and Edge/workerd runtimes). Guarantees that concurrent SSR module evaluations, HMR invalidations, and singleton states do not cross-contaminate or leak heap memory across runtime compilation contexts. globs: vite.config.{ts,js,mjs}, src/**/*.{ts,tsx,js,jsx}, server/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-ssr-environment-runtime-isolation" --- # Vite 6 Environment API Multi-Runtime SSR Isolation & Memory Leak Prevention > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Runtime Global Mutation and Uncollected ModuleRunner Closures in Multi-Environment SSR ## System Constraints You are a Principal Engineer enforcing Vite 6 Environment API SSR Multi-Runtime Memory Isolation. Mandate complete runtime boundary separation between Node.js and Edge Worker execution contexts. Prohibit cross-environment module caching, globalThis state pollution, and uncleared hot module replacement (HMR) subscriptions that lead to memory leaks and cross-isolate state contamination. ## Strict Guidelines - Engineers MUST ALWAYS isolate stateful services (e.g., ORMs, caches, telemetry) per Vite DevEnvironment instance rather than instantiating them on top-level globalThis or shared module closures. - Engineers MUST NOT import Node.js-evaluated modules directly into an Edge DevEnvironment runner (such as Cloudflare workerd or Miniflare); module resolution MUST route through environment-specific ModuleRunner instances. - Engineers MUST ALWAYS implement import.meta.hot.dispose() cleanup handlers when creating persistent runtime clients or event emitters to prevent stale isolate references after HMR invalidation. - Code SHOULD leverage AsyncLocalStorage or explicit request-scoped dependency containers rather than ambient singletons for SSR render pipelines executing concurrently across environments. - Services MUST ensure that server.environments[envName].moduleRunner is instantiated with dedicated transform and fetch pipelines to avoid sharing module graph transform caches between incompatible targets. ## Bad vs Good Implementations ### Multi-Runtime DevEnvironment Configuration and Isolated Module Runner #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using legacy ssrLoadModule bypasses Vite 6 Environment API, forcing both Edge and Node targets into the identical Node process isolate. Global state pollution on globalThis creates cross-isolate memory contamination, and module graphs are not cleared upon environment-specific HMR events. ```typescript import { createServer } from 'vite'; // ANTI-PATTERN: Shared global registry accessible across runtimes. // Node and Edge compilation contexts will overwrite each other's state // and retain references across HMR cycles. declare global { var __SSR_CACHE__: Map<string, any> | undefined; } globalThis.__SSR_CACHE__ = globalThis.__SSR_CACHE__ || new Map(); export async function createDevServer() { const server = await createServer({ server: { middlewareMode: true }, appType: 'custom', }); // Flawed: Executing Edge code directly in Node host context using deprecated ssrLoadModule const edgeHandler = await server.ssrLoadModule('/src/entry.edge.ts'); const nodeHandler = await server.ssrLoadModule('/src/entry.node.ts'); return { server, edgeHandler, nodeHandler }; } ``` #### Production Standard (Correct) > **Standard**: Configures dedicated Vite 6 DevEnvironment targets with explicit conditions. Uses createServerModuleRunner for discrete module graphs and registers beforeUpdate hooks to guarantee garbage collection of evaluated modules across independent runtimes. ```typescript import { createServer, DevEnvironment } from 'vite'; import { createServerModuleRunner } from 'vite/module-runner'; // ISOLATED PATTERN: Scoped context factory per DevEnvironment interface RuntimeContext { cache: Map<string, unknown>; dispose: () => void; } export function createEnvironmentContext(): RuntimeContext { const cache = new Map<string, unknown>(); return { cache, dispose: () => { cache.clear(); }, }; } export async function createDevServer() { const server = await createServer({ server: { middlewareMode: true }, appType: 'custom', environments: { node: { build: { outDir: 'dist/node' }, }, edge: { resolve: { conditions: ['worker', 'webworker'] }, build: { outDir: 'dist/edge' }, }, }, }); // Isolate Edge DevEnvironment via Vite 6 ModuleRunner const edgeEnv = server.environments.edge as DevEnvironment; const nodeEnv = server.environments.node as DevEnvironment; const edgeRunner = createServerModuleRunner(edgeEnv); const nodeRunner = createServerModuleRunner(nodeEnv); // Ensure HMR invalidation disposes environment-specific cached singletons edgeEnv.hot.on('vite:beforeUpdate', () => { edgeRunner.clearCache(); }); nodeEnv.hot.on('vite:beforeUpdate', () => { nodeRunner.clearCache(); }); return { server, edgeRunner, nodeRunner }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API Multi-Runtime SSR Isolation & Memory Leak Prevention

Vite 6 Environment API Multi-Runtime SSR Isolation & Memory Leak Prevention defines an industrial-grade behavioral standard for frontend engineering. Enforces strict heap separation and lifecycle boundary governance across Vite 6 DevEnvironment instances (e.g., Node.js and Edge/workerd runtimes). Guarantees that concurrent SSR module evaluations, HMR invalidations, and singleton states do not cross-contaminate or leak heap memory across runtime compilation contexts. 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-Runtime Global Mutation and Uncollected ModuleRunner Closures in Multi-Environment 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	Cross-Runtime Global Mutation and Uncollected ModuleRunner Closures in Multi-Environment 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 isolate stateful services (e.g., ORMs, caches, telemetry) per Vite DevEnvironment instance rather than instantiating them on top-level globalThis or shared module closures.

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.