Vite 6 Environment API WeakRef & FinalizationRegistry Context Reclamation

--- description: Vite 6 Environment API WeakRef & FinalizationRegistry Context Reclamation - Enforces strict memory reclamation for multi-runtime SSR module evaluations using Vite 6's Environment API. Strong references to transient DevEnvironment runner scopes, execution contexts, and evaluated module graphs MUST be replaced with WeakRef and tracked via FinalizationRegistry to prevent fatal heap exhaustion during Hot Module Replacement (HMR). globs: vite.config.ts, src/server/**/*.{ts,js}, src/entry-server/**/*.{ts,tsx}, server/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-environment-weakref-context-gc-guardrail" --- # Vite 6 Environment API WeakRef & FinalizationRegistry Context Reclamation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Retaining Strong References to Multi-Runtime SSR ModuleRunner Contexts Across HMR Cycles ## System Constraints You are a Principal Software Architect enforcing zero-leak Vite 6 Environment API lifecycle rules. In Vite 6 multi-runtime setups (workerd, node, edge), dynamic module evaluation contexts create transient closures. You must ensure all dev server evaluation contexts, runners, and module registries are bounded by WeakRef and FinalizationRegistry guards, ensuring memory is reclaimed immediately upon HMR invalidation. ## Strict Guidelines - Engineers MUST ALWAYS store transient `DevEnvironment` execution contexts and `ModuleRunner` instances using `WeakRef` within long-lived server registries. - Engineers MUST NOT cache evaluated SSR module namespaces or runner evaluations in global Maps or module-scope strong collections across HMR boundaries. - Code SHOULD register every created execution context with a `FinalizationRegistry` to log and assert deterministic teardown during continuous dev iterations. - Services MUST explicitly invoke `runner.close()` and detach runtime module nodes upon receiving Vite environment `close` or `hot.invalidate` signals. - Components NEVER hold circular closures referencing the SSR evaluation runtime or environment transport layer inside server request handlers. ## Bad vs Good Implementations ### WeakRef and FinalizationRegistry Bound SSR Module Evaluation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Storing `runner` or execution contexts in a permanent Map retains strong references to V8 contexts, module graphs, and synthetic module evaluators. Across dozens of HMR edits, previous environments cannot be garbage-collected, triggering chronic heap exhaustion and dev server crashes. ```typescript import { createServer, type ViteDevServer } from 'vite'; // ANTI-PATTERN: Strong Map storing runner instances permanently leaks // old environments, V8 closures, and module graphs across HMR cycles. const runnerCache = new Map<string, any>(); export async function handleSsrRequest(server: ViteDevServer, envName: string, url: string) { let runner = runnerCache.get(envName); if (!runner) { const environment = server.environments[envName]; // Retains hard reference to runner and its entire closure scope runner = environment.runner; runnerCache.set(envName, runner); } const mod = await runner.import('/src/entry-server.ts'); return mod.render(url); } ``` #### Production Standard (Correct) > **Standard**: The runner reference is stored as a `WeakRef`, allowing the V8 garbage collector to sweep the transient evaluation context and module graphs when the environment is disposed or replaced during HMR. The `FinalizationRegistry` confirms context destruction without creating strong memory anchors. ```typescript import type { ViteDevServer, DevEnvironment } from 'vite'; interface ExecutionHandle { runnerRef: WeakRef<NonNullable<DevEnvironment['runner']>>; } const registry = new FinalizationRegistry<string>((envName) => { if (process.env.NODE_ENV !== 'production') { console.debug(`[Vite GC] Transient execution context for '${envName}' successfully collected.`); } }); const transientRunners = new Map<string, ExecutionHandle>(); export async function handleSsrRequest(server: ViteDevServer, envName: string, url: string) { const environment = server.environments[envName]; if (!environment) { throw new Error(`Environment ${envName} not found`); } const existingHandle = transientRunners.get(envName); let runner = existingHandle?.runnerRef.deref(); if (!runner) { const newRunner = environment.runner; if (!newRunner) { throw new Error(`Runner is unavailable for environment ${envName}`); } const ref = new WeakRef(newRunner); transientRunners.set(envName, { runnerRef: ref }); registry.register(newRunner, envName); runner = newRunner; } // Execute evaluation without leaking namespace in static scope const mod = await runner.import('/src/entry-server.ts'); return mod.render(url); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Environment API WeakRef & FinalizationRegistry Context Reclamation

Vite 6 Environment API WeakRef & FinalizationRegistry Context Reclamation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict memory reclamation for multi-runtime SSR module evaluations using Vite 6's Environment API. Strong references to transient DevEnvironment runner scopes, execution contexts, and evaluated module graphs MUST be replaced with WeakRef and tracked via FinalizationRegistry to prevent fatal heap exhaustion during Hot Module Replacement (HMR). 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: Retaining Strong References to Multi-Runtime SSR ModuleRunner Contexts Across HMR Cycles 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	Retaining Strong References to Multi-Runtime SSR ModuleRunner Contexts Across HMR Cycles	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 store transient `DevEnvironment` execution contexts and `ModuleRunner` instances using `WeakRef` within long-lived server registries.

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.