fix: debounce fs route hmr events, avoid reload for existing routes

Author: katywings

packages/start/src/config/constants.ts

@@ -14,6 +14,6 @@ export const VIRTUAL_MODULES = {
 } as const;
 
 export const VITE_ENVIRONMENTS = {
-  client: "client",
-  server: "ssr",
+  client: "client" as const,
+  server: "ssr" as const,
 };

packages/start/src/config/fs-routes/fs-watcher.ts

@@ -1,56 +1,52 @@
-import type {
-  EnvironmentModuleNode,
-  FSWatcher,
-  PluginOption,
-  ViteDevServer,
-} from "vite";
+import type { EnvironmentModuleNode, FSWatcher, PluginOption, ViteDevServer } from "vite";
+import { debounce } from "../../utils/debounce.ts";
 import { VITE_ENVIRONMENTS } from "../constants.ts";
 import { moduleId } from "./index.ts";
 import type { BaseFileSystemRouter } from "./router.ts";
 
-interface CompiledRouter {
-  removeRoute(path: string): void;
-  addRoute(path: string): void;
-  updateRoute(path: string): void;
-  addEventListener(event: "reload", handler: () => void): void;
-  removeEventListener(event: "reload", handler: () => void): void;
-}
-
-function setupWatcher(watcher: FSWatcher, routes: CompiledRouter): void {
+function setupWatcher(watcher: FSWatcher, routes: BaseFileSystemRouter): void {
   watcher.on("unlink", path => routes.removeRoute(path));
   watcher.on("add", path => routes.addRoute(path));
   watcher.on("change", path => routes.updateRoute(path));
 }
 
 function createRoutesReloader(
   server: ViteDevServer,
-  routes: CompiledRouter,
+  routes: BaseFileSystemRouter,
   environment: "client" | "ssr",
-): () => void {
-  routes.addEventListener("reload", handleRoutesReload);
-  return () => routes.removeEventListener("reload", handleRoutesReload);
+) {
+  const devEnv = server.environments[environment]!;
+  if (!devEnv?.moduleGraph) return;
+
+  /**
+   * Debounce catches multiple route changes in a row
+   * Short timeout for inexpensive invalidations11
+   */
+  const invalidateModule = debounce((mod: EnvironmentModuleNode) => {
+    devEnv.moduleGraph.invalidateModule(mod);
+  }, 0);
 
-  function handleRoutesReload(): void {
-    const envName =
-      environment === "ssr" ? VITE_ENVIRONMENTS.server : VITE_ENVIRONMENTS.client;
-    const devEnv = server.environments[envName];
-    if (!devEnv?.moduleGraph) return;
+  /**
+   * Long debounce timeout for expensive reloads
+   */
+  const reloadModule = debounce((mod: EnvironmentModuleNode) => {
+    devEnv.reloadModule(mod);
+  }, 200);
 
-    const mod: EnvironmentModuleNode | undefined =
-      devEnv.moduleGraph.getModuleById(moduleId);
-    if (mod) {
-      const seen = new Set<EnvironmentModuleNode>();
-      devEnv.moduleGraph.invalidateModule(mod, seen);
+  return routes.on("reload", function handleRoutesReload(evt): void {
+    const mod = devEnv.moduleGraph.getModuleById(moduleId)!;
+    if (!mod) {
+      devEnv.hot.send({ type: "full-reload" });
+      return;
     }
 
-    if (environment !== "ssr") {
-      if (mod) {
-        devEnv.reloadModule(mod);
-      } else if (devEnv.hot) {
-        devEnv.hot.send({ type: "full-reload" });
-      }
+    if (environment === VITE_ENVIRONMENTS.client && evt.detail.type !== "update") {
+      // Client has to be reloaded when routes are added or removed
+      reloadModule(mod);
+    } else {
+      invalidateModule(mod);
     }
-  }
+  });
 }
 
 export const fileSystemWatcher = (
@@ -59,11 +55,11 @@ export const fileSystemWatcher = (
   const plugin: PluginOption = {
     name: "fs-watcher",
     async configureServer(server: ViteDevServer) {
-      Object.keys(routers).forEach(environment => {
-        const router = (globalThis as any).ROUTERS[environment];
+      for (const environment of [VITE_ENVIRONMENTS.server, VITE_ENVIRONMENTS.client]) {
+        const router = routers[environment];
         setupWatcher(server.watcher, router);
-        createRoutesReloader(server, router, environment as keyof typeof routers);
-      });
+        createRoutesReloader(server, router, environment);
+      }
     },
   };
   return plugin;

packages/start/src/config/fs-routes/router.ts

@@ -32,6 +32,8 @@ export function analyzeModule(src: string) {
   );
 }
 
+type RouterEvent = CustomEvent<{ route: string; type: "update" | "remove" | "add" }>;
+
 export class BaseFileSystemRouter extends EventTarget {
   routes: Route[];
 
@@ -109,20 +111,20 @@ export class BaseFileSystemRouter extends EventTarget {
         const route = this.toRoute(src);
         if (route) {
           this._addRoute(route);
-          this.reload(route.path);
+          this.reload(route.path, "add");
         }
       } catch (e) {
         console.error(e);
       }
     }
   }
 
-  reload(route: string) {
+  reload(route: string, type: "update" | "remove" | "add") {
     this.dispatchEvent(
-      new Event("reload", {
-        // @ts-ignore
+      new CustomEvent("reload", {
         detail: {
           route,
+          type,
         },
       }),
     );
@@ -135,7 +137,7 @@ export class BaseFileSystemRouter extends EventTarget {
         const route = this.toRoute(src);
         if (route) {
           this._addRoute(route);
-          this.reload(route.path);
+          this.reload(route.path, "update");
         }
       } catch (e) {
         console.error(e);
@@ -152,10 +154,15 @@ export class BaseFileSystemRouter extends EventTarget {
         return;
       }
       this.routes = this.routes.filter(r => r.path !== path);
-      this.dispatchEvent(new Event("reload", {}));
+      this.reload(path, "remove");
     }
   }
 
+  on(type: string, cb: (evt: RouterEvent) => void) {
+    this.addEventListener(type, cb as any);
+    return () => this.removeEventListener(type, cb as any);
+  }
+
   buildRoutesPromise?: Promise<any[]>;
 
   async getRoutes() {

packages/start/src/utils/debounce.ts

@@ -0,0 +1,10 @@
+/**
+ * Creates a debounced function that delays the invocation of a function
+ */
+export const debounce = <T extends (...args: any[]) => void>(cb: T, debounceMs: number) => {
+  let timeout: NodeJS.Timeout | undefined;
+  return (...args: Parameters<T>) => {
+    clearTimeout(timeout);
+    timeout = setTimeout(() => cb(...args), debounceMs)
+  }
+}