fix: don't send browser full-reload for server-only modules by default

hotUpdate hook now separates server-only vs shared modules.
Browser full-reload only sent when serverReload option is true (default false).
Shared modules continue through normal HMR pipeline.
Adds e2e tests for both default (no reload) and serverReload:true behaviors.

Author: schiller-manuel

examples/vite-ssr-react/vite.config.server-reload.mjs

@@ -0,0 +1,12 @@
+import { defineConfig } from "vite";
+import { nitro } from "nitro/vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [nitro({ experimental: { vite: { serverReload: true } } }), react()],
+  environments: {
+    client: {
+      build: { rollupOptions: { input: "./src/entry-client.tsx" } },
+    },
+  },
+});

src/build/vite/plugin.ts

@@ -238,31 +238,33 @@ function nitroMain(ctx: NitroPluginContext): VitePlugin {
       return configureViteDevServer(ctx, server);
     },
 
-    // Automatically reload the client when a server module is updated
+    // Invalidate server-only modules and optionally reload the browser
     // see: https://github.com/vitejs/vite/issues/19114
     async hotUpdate({ server, modules, timestamp }) {
       const env = this.environment;
-      if (
-        ctx.pluginConfig.experimental?.vite.serverReload === false ||
-        env.config.consumer === "client"
-      ) {
+      if (env.config.consumer === "client") {
         return;
       }
       const clientEnvs = Object.values(server.environments).filter(
         (env) => env.config.consumer === "client"
       );
-      let hasServerOnlyModule = false;
+      const serverOnlyModules: EnvironmentModuleNode[] = [];
+      const sharedModules: EnvironmentModuleNode[] = [];
       const invalidated = new Set<EnvironmentModuleNode>();
       for (const mod of modules) {
         if (mod.id && !clientEnvs.some((env) => env.moduleGraph.getModuleById(mod.id!))) {
-          hasServerOnlyModule = true;
+          serverOnlyModules.push(mod);
           env.moduleGraph.invalidateModule(mod, invalidated, timestamp, false);
+        } else {
+          sharedModules.push(mod);
         }
       }
-      if (hasServerOnlyModule) {
+      if (serverOnlyModules.length > 0) {
         env.hot.send({ type: "full-reload" });
-        server.ws.send({ type: "full-reload" });
-        return [];
+        if (sharedModules.length === 0 && ctx.pluginConfig.experimental?.vite.serverReload) {
+          server.ws.send({ type: "full-reload" });
+        }
+        return sharedModules;
       }
     },
   };

src/build/vite/types.ts

@@ -30,9 +30,14 @@ export interface NitroPluginConfig extends NitroConfig {
       assetsImport?: boolean;
 
       /**
-       * Reload the page when a server module is updated.
+       * Reload the browser page when a server-only module is updated.
        *
-       * @default true
+       * When disabled, server-only module changes will still invalidate the
+       * server runtime but won't trigger a browser full-reload. This prevents
+       * destroying client-side HMR updates when a file produces both client
+       * and server-only modules.
+       *
+       * @default false
        */
       serverReload?: boolean;
 

test/hot-update.test.ts

@@ -0,0 +1,163 @@
+import { join } from "node:path";
+import { readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import type { ViteDevServer } from "vite";
+
+const { createServer } = (await import(
+  process.env.NITRO_VITE_PKG || "vite"
+)) as typeof import("vite");
+
+const rootDir = fileURLToPath(new URL("../examples/vite-ssr-react", import.meta.url));
+
+function getBaseURL(server: ViteDevServer): string {
+  const addr = server.httpServer?.address() as {
+    port: number;
+    address: string;
+    family: string;
+  };
+  return `http://${addr.family === "IPv6" ? `[${addr.address}]` : addr.address}:${addr.port}`;
+}
+
+/**
+ * Intercept messages sent via server.ws.send and collect them for a duration.
+ */
+function collectWsMessages(server: ViteDevServer, duration: number): Promise<any[]> {
+  return new Promise((resolve) => {
+    const messages: any[] = [];
+    const origSend = server.ws.send.bind(server.ws);
+    server.ws.send = function (payload: any) {
+      messages.push(payload);
+      return origSend(payload);
+    };
+    setTimeout(() => {
+      server.ws.send = origSend;
+      resolve(messages);
+    }, duration);
+  });
+}
+
+describe("vite hotUpdate", () => {
+  let server: ViteDevServer;
+  const appFile = join(rootDir, "src/app.tsx");
+  const serverFile = join(rootDir, "src/entry-server.tsx");
+  let originalApp: string;
+  let originalServer: string;
+
+  beforeAll(async () => {
+    originalApp = readFileSync(appFile, "utf-8");
+    originalServer = readFileSync(serverFile, "utf-8");
+
+    process.chdir(rootDir);
+    server = await createServer({ root: rootDir });
+    await server.listen("0" as unknown as number);
+
+    // Fetch the page so the SSR environment loads all modules
+    await fetch(getBaseURL(server) + "/");
+    await new Promise((r) => setTimeout(r, 1000));
+  }, 30_000);
+
+  afterAll(async () => {
+    writeFileSync(appFile, originalApp);
+    writeFileSync(serverFile, originalServer);
+    await server?.close();
+  });
+
+  test("editing shared module does not trigger browser full-reload", async () => {
+    const collecting = collectWsMessages(server, 2000);
+
+    const modified = originalApp.replace("Nitro + Vite + React", "Nitro + Vite + React EDITED");
+    writeFileSync(appFile, modified);
+
+    const messages = await collecting;
+
+    const fullReloads = messages.filter((m) => typeof m === "object" && m?.type === "full-reload");
+    expect(
+      fullReloads,
+      "browser should not receive full-reload for shared module edits"
+    ).toHaveLength(0);
+
+    // Server should render updated content on next request
+    const html = await fetch(getBaseURL(server) + "/").then((r) => r.text());
+    expect(html).toContain("Nitro + Vite + React EDITED");
+
+    // Restore
+    writeFileSync(appFile, originalApp);
+    await new Promise((r) => setTimeout(r, 500));
+  });
+
+  test("editing server-only module does not trigger browser full-reload by default", async () => {
+    const collecting = collectWsMessages(server, 2000);
+
+    const modified = originalServer.replace(
+      '<meta name="viewport"',
+      '<meta name="description" content="hot-update-test" />\n            <meta name="viewport"'
+    );
+    writeFileSync(serverFile, modified);
+
+    const messages = await collecting;
+
+    const fullReloads = messages.filter((m) => typeof m === "object" && m?.type === "full-reload");
+    expect(
+      fullReloads,
+      "browser should not receive full-reload when serverReload is disabled (default)"
+    ).toHaveLength(0);
+
+    // Server should render updated content on next request
+    const html = await fetch(getBaseURL(server) + "/").then((r) => r.text());
+    expect(html).toContain('content="hot-update-test"');
+
+    // Restore
+    writeFileSync(serverFile, originalServer);
+  });
+});
+
+describe("vite hotUpdate (serverReload: true)", () => {
+  let server: ViteDevServer;
+  const serverFile = join(rootDir, "src/entry-server.tsx");
+  let originalServer: string;
+
+  beforeAll(async () => {
+    originalServer = readFileSync(serverFile, "utf-8");
+
+    process.chdir(rootDir);
+    server = await createServer({
+      root: rootDir,
+      configFile: join(rootDir, "vite.config.server-reload.mjs"),
+    });
+    await server.listen("0" as unknown as number);
+
+    // Fetch the page so the SSR environment loads entry-server.tsx
+    await fetch(getBaseURL(server) + "/");
+  }, 30_000);
+
+  afterAll(async () => {
+    writeFileSync(serverFile, originalServer);
+    await server?.close();
+  });
+
+  test("editing server-only module triggers browser full-reload when serverReload is enabled", async () => {
+    const collecting = collectWsMessages(server, 2000);
+
+    const modified = originalServer.replace(
+      '<meta name="viewport"',
+      '<meta name="description" content="reload-test" />\n            <meta name="viewport"'
+    );
+    writeFileSync(serverFile, modified);
+
+    const messages = await collecting;
+
+    const fullReloads = messages.filter((m) => typeof m === "object" && m?.type === "full-reload");
+    expect(
+      fullReloads,
+      "browser should receive full-reload when serverReload is enabled and all modules are server-only"
+    ).not.toHaveLength(0);
+
+    // Server should render updated content on next request
+    const html = await fetch(getBaseURL(server) + "/").then((r) => r.text());
+    expect(html).toContain('content="reload-test"');
+
+    // Restore
+    writeFileSync(serverFile, originalServer);
+  });
+});