fix: Vite HMR broken when using reactDevtools() plugin (#34)

Author: piotrski

.changeset/fix-vite-hmr.md

@@ -0,0 +1,5 @@
+---
+"agent-react-devtools": patch
+---
+
+Fixed Vite HMR (hot module replacement) breaking when the `reactDevtools()` plugin is added to `vite.config.ts`. The connect module now preserves the react-refresh runtime's inject wrapper when replacing the devtools hook, so both Fast Refresh and devtools inspection work correctly.

packages/agent-react-devtools/src/connect.ts

@@ -57,6 +57,11 @@ const isProd =
 // This MUST happen at module evaluation time — if deferred to an async
 // callback, react-dom may initialize first and miss the hook entirely.
 if (!isSSR && !isProd) {
+  // Save any existing inject wrapper (e.g., react-refresh runtime from
+  // @vitejs/plugin-react) before replacing the hook stub.
+  const oldHook = (window as any).__REACT_DEVTOOLS_GLOBAL_HOOK__;
+  const oldInject = oldHook?.inject;
+
   // Remove Vite's plugin-react hook stub so react-devtools-core can install the full hook
   try {
     delete (window as any).__REACT_DEVTOOLS_GLOBAL_HOOK__;
@@ -65,6 +70,24 @@ if (!isSSR && !isProd) {
   }
 
   initialize();
+
+  // If the old hook had a wrapped inject (from react-refresh runtime),
+  // re-apply it so Fast Refresh / HMR continues to work. The refresh
+  // wrapper inspects the `injected` argument to capture scheduleRefresh;
+  // calling it after the real inject ensures both devtools and HMR work.
+  const newHook = (window as any).__REACT_DEVTOOLS_GLOBAL_HOOK__;
+  if (oldInject && newHook && oldInject !== newHook.inject) {
+    const realInject = newHook.inject;
+    newHook.inject = function (injected: unknown) {
+      const id = realInject.apply(this, arguments);
+      try {
+        oldInject.call(this, injected);
+      } catch {
+        // Ignore errors from the old stub inject
+      }
+      return id;
+    };
+  }
 }
 
 export const ready: Promise<void> = isSSR || isProd ? noop() : connect();

packages/agent-react-devtools/src/vite-plugin.ts

@@ -15,16 +15,13 @@ export function reactDevtools(options?: ReactDevtoolsOptions): Plugin {
     name: 'agent-react-devtools',
     apply: 'serve',
     config() {
-      // The connect module uses top-level await to block React from loading
-      // before the devtools hook is installed. Vite's dep optimizer uses
-      // esbuild which defaults to es2020 (no TLA support), so we enable it.
+      // The connect module is injected via transformIndexHtml, so Vite's
+      // dep scanner won't discover react-devtools-core (a CJS package)
+      // until the page loads. Without this hint, Vite triggers dep
+      // re-optimization at runtime which causes a full-reload and breaks HMR.
       return {
         optimizeDeps: {
-          esbuildOptions: {
-            supported: {
-              'top-level-await': true,
-            },
-          },
+          include: ['react-devtools-core'],
         },
       };
     },

packages/e2e-tests/src/browser.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import { chromium, type Browser, type Page } from 'playwright';
 import path from 'node:path';
+import fs from 'node:fs';
 import type { ChildProcess } from 'node:child_process';
 import {
   createTempStateDir,
@@ -121,4 +122,47 @@ describe('Browser e2e', () => {
     expect(summary.commitCount).toBeGreaterThan(0);
     expect(summary.componentRenderCounts.length).toBeGreaterThan(0);
   });
+
+  it('HMR works — file change applies without full reload', async () => {
+    const appFile = path.resolve(
+      import.meta.dirname,
+      '../../../examples/vite-app/src/App.tsx',
+    );
+    const original = fs.readFileSync(appFile, 'utf-8');
+
+    try {
+      // Set a window marker to detect full page reloads
+      await page.evaluate(() => {
+        (window as any).__hmrMarker = 'alive';
+      });
+
+      // Verify the original heading is present
+      const h1 = page.locator('h1');
+      expect(await h1.textContent()).toBe('Perf Debug App');
+
+      // Modify the heading text
+      const modified = original.replace('Perf Debug App', 'HMR Test Heading');
+      fs.writeFileSync(appFile, modified, 'utf-8');
+
+      // Wait for HMR to apply the change
+      const deadline = Date.now() + 10_000;
+      let found = false;
+      while (Date.now() < deadline) {
+        const text = await h1.textContent().catch(() => null);
+        if (text === 'HMR Test Heading') {
+          found = true;
+          break;
+        }
+        await sleep(250);
+      }
+      expect(found, 'File change should be reflected in the browser').toBe(true);
+
+      // Verify no full page reload occurred — the marker should still be set
+      const marker = await page.evaluate(() => (window as any).__hmrMarker);
+      expect(marker).toBe('alive');
+    } finally {
+      // Always restore the original file
+      fs.writeFileSync(appFile, original, 'utf-8');
+    }
+  });
 });