Vite 6 Module Federation Hot Module Replacement (HMR) State Reconciliation Guardrail

--- description: Vite 6 Module Federation Hot Module Replacement (HMR) State Reconciliation Guardrail - Enforces deterministic cross-remote module graph invalidation, isolated boundary lifecycle disposal, and synchronized runtime registry cleanup during Hot Module Replacement (HMR) in Vite 6 Module Federation architectures. Eliminates cascade invalidation loops, memory leaks from dangling host listeners, and catastrophic full-page reloads when shared dependencies or exposed federation modules are updated in development mode. globs: vite.config.{ts,js,mjs}, src/remotes/**/*.{ts,tsx,js,jsx}, src/bootstrap.{ts,tsx}, src/federation/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-module-federation-hmr-state-reconciliation" --- # Vite 6 Module Federation Hot Module Replacement (HMR) State Reconciliation Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cascade Boundary Invalidation and Leaked Remote State Causing Cyclic Hard Refreshes in Vite 6 MF ## System Constraints You are a Principal Engineer enforcing the Vite 6 Module Federation Hot Module Replacement (HMR) State Reconciliation Guardrail. Mandate that all cross-remote dynamic imports, shared runtime state stores, and federation boundary entrypoints implement deterministic import.meta.hot lifecycle hooks (accept, dispose, prune, data). Prevent raw module re-evaluations from bypassing the remote container registry or triggering global window reload events. Ensure clean micro-frontend unmounting, DOM node release, and event listener tear-down across host/remote boundaries. ## Strict Guidelines - Engineers MUST ALWAYS implement import.meta.hot.dispose() hooks at the host-remote boundary to unmount mounted root components, detach global window listeners, and invalidate local singleton cache entries before accepting updated code. - Engineers MUST ALWAYS define import.meta.hot.accept() targeting explicit boundary interfaces rather than self-accepting leaf nodes inside dynamic federated federation modules, preventing Vite from traversing upward to the root and triggering location.reload(). - Engineers MUST NOT allow shared global state singletons (e.g., Zustand, Redux, React Context) across remotes to re-instantiate during HMR without preserving state continuity via import.meta.hot.data payloads. - Code MUST isolate Vite 6 environment module graph traversal by setting explicit hmr: { overlay: true } and ensuring remote origins configure Access-Control-Allow-Origin headers compatible with Vite WebSocket/SSE endpoints. - Remote container wrappers MUST handle unresolved promises during in-flight HMR replacements by aborting obsolete pending remote chunks using AbortController signals. - Components NEVER execute raw dynamic import() calls to federated remotes inside render cycles without a designated ErrorBoundary and React.Suspense fallback that handles transient runtime chunk 404/500 errors during remote Vite server restarts. ## Bad vs Good Implementations ### Federated Remote Boundary HMR Lifecycle with State Preservation and Clean Disposal #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Lacks an import.meta.hot boundary and explicit cleanup. When the remote Vite dev server pushes an HMR update for 'remoteBilling/Widget', the host's module graph cannot reconcile the change across the federation boundary, triggering an uncontrolled cascade invalidation that forces a hard browser page reload and destroys user session state. ```typescript // BAD: Blind dynamic import without HMR boundary handling or unmount disposal. // Remote updates propagate unhandled to root, causing full host browser reload. import React, { lazy, Suspense } from 'react'; const RemoteBillingWidget = lazy(() => import('remoteBilling/Widget')); export const BillingContainer: React.FC = () => { return ( <div> <h3>Host Billing View</h3> <Suspense fallback={<div>Loading Remote Billing...</div>}> <RemoteBillingWidget /> </Suspense> </div> ); }; ``` #### Production Standard (Correct) > **Standard**: Implements an explicit import.meta.hot.accept handler for the federated remote boundary, stores state in import.meta.hot.data, cleans up lingering side-effects in import.meta.hot.dispose, and wraps dynamic boundaries in an ErrorBoundary to recover gracefully without triggering full-page reload loops. ```typescript // GOOD: Deterministic HMR boundary handling with container unmounting, state handover, and safe acceptance. import React, { Component, ErrorInfo, ReactNode, lazy, Suspense } from 'react'; interface BoundaryState { hasError: boolean; errorKey: number; } export class RemoteErrorBoundary extends Component<{ children: ReactNode }, BoundaryState> { state: BoundaryState = { hasError: false, errorKey: 0 }; static getDerivedStateFromError(): BoundaryState { return { hasError: true, errorKey: Date.now() }; } componentDidCatch(error: Error, info: ErrorInfo): void { console.warn('[HMR:RemoteBoundary] Handled runtime error during remote swap:', error, info); } resetBoundary = (): void => { this.setState((prev) => ({ hasError: false, errorKey: prev.errorKey + 1 })); }; render(): ReactNode { if (this.state.hasError) { return ( <div role="alert" className="p-4 border border-amber-500 rounded"> <p>Remote module transient update failure.</p> <button onClick={this.resetBoundary} className="btn-retry">Retry</button> </div> ); } return <React.Fragment key={this.state.errorKey}>{this.props.children}</React.Fragment>; } } let RemoteBillingWidget = lazy(() => import('remoteBilling/Widget')); export const BillingContainer: React.FC = () => { return ( <div> <h3>Host Billing View</h3> <RemoteErrorBoundary> <Suspense fallback={<div>Loading Remote Billing...</div>}> <RemoteBillingWidget /> </Suspense> </RemoteErrorBoundary> </div> ); }; if (import.meta.hot) { // Persist transient boundary metadata across hot replacement cycles import.meta.hot.data.renderTimestamp = Date.now(); import.meta.hot.accept(['remoteBilling/Widget'], (modules) => { const updatedModule = modules[0]; if (updatedModule) { // Reassign lazy loader to freshly evaluated remote module export RemoteBillingWidget = lazy(() => Promise.resolve(updatedModule)); } }); import.meta.hot.dispose((data) => { data.lastDisposedAt = Date.now(); // Detach any dangling remote event subscriptions or workers window.dispatchEvent(new CustomEvent('mf:remote-dispose', { detail: { remote: 'remoteBilling' } })); }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Module Federation Hot Module Replacement (HMR) State Reconciliation Guardrail

Vite 6 Module Federation Hot Module Replacement (HMR) State Reconciliation Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic cross-remote module graph invalidation, isolated boundary lifecycle disposal, and synchronized runtime registry cleanup during Hot Module Replacement (HMR) in Vite 6 Module Federation architectures. Eliminates cascade invalidation loops, memory leaks from dangling host listeners, and catastrophic full-page reloads when shared dependencies or exposed federation modules are updated in development mode. 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: Cascade Boundary Invalidation and Leaked Remote State Causing Cyclic Hard Refreshes in Vite 6 MF 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	Cascade Boundary Invalidation and Leaked Remote State Causing Cyclic Hard Refreshes in Vite 6 MF	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 implement import.meta.hot.dispose() hooks at the host-remote boundary to unmount mounted root components, detach global window listeners, and invalidate local singleton cache entries before accepting updated code.

Engineers MUST ALWAYS implement import.meta.hot.dispose() hooks at the host-remote boundary to unmount mounted root components, detach global window listeners, and invalidate local singleton cache entries before accepting updated code.

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.