@uniflowed/router 0.13.1 → 0.14.0

package/client.js

@@ -122,6 +122,14 @@ import { type TrailingSlash, addressOf, applicationPathOf } from "./internal/bas
 import { hydrationOptions } from "./internal/hydrate-options.js";
 import { readFormState } from "./internal/form-action.js";
 
+// What `virtual:uf/client` calls in development to take a dev server's edits
+// as renders rather than reloads; see "Hot updates" in `./internal/runtime.js`.
+export {
+  acceptHotRouteModules,
+  refreshForHotUpdate,
+  replaceRoutesForHotUpdate,
+} from "./internal/runtime.js";
+
 /**
  * The React root `hydrate` and `render` mounted, as far as a caller needs it:
  * a way to take the application down again. See `hydrate` for who needs that.

package/internal/flight-browser.js

@@ -65,6 +65,25 @@ export function installServerCallback(): void {
   setServerCallback(callServerReference);
 }
 
+/**
+ * The newest evaluation of the client module at `url`, in development.
+ *
+ * `@uniflowed/vite`'s Fast Refresh wrapper publishes every evaluation of a
+ * component module under its path, in `window.__UF_LATEST_MODULES__`. A
+ * client reference is a `React.lazy` that React matches against the component
+ * already mounted by identity, and after a hot update that component is the
+ * module's *newest* evaluation — so a payload that answered with the first one
+ * would be a different component, and a server edit would remount every client
+ * component it rendered, state and all. The registry never exists in a build.
+ */
+function latestModule(url: string): ?ModuleNamespace {
+  const registry = window.__UF_LATEST_MODULES__;
+  if (registry == null) {
+    return null;
+  }
+  return registry.get(new URL(url, window.location.href).pathname);
+}
+
 /**
  * Install the module hook React's Flight client resolves references through.
  *
@@ -80,7 +99,7 @@ export function installBrowserModules(): void {
   // chunk it lives in. Declared and then given its properties, so the hook is
   // built rather than merged into something that already existed.
   function parcelRequire(id: string): ModuleNamespace {
-    const namespace = loaded.get(id);
+    const namespace = latestModule(id) ?? loaded.get(id);
     if (namespace == null) {
       throw new Error(
         `@uniflowed/router: the client module ${id} was required before it loaded. React's ` +

package/internal/resolve.js

@@ -649,7 +649,53 @@ type InterceptedUrl = {|
 
 const moduleCache: Map<() => Promise<mixed>, Promise<mixed>> = new Map();
 
+/**
+ * Route modules a dev server replaced, by the key their loader carries.
+ *
+ * A loader is `() => import("/app/$page.js")`, and asking it again after a hot
+ * update returns the module the browser evaluated first — the browser keys
+ * modules by URL, and the update arrived under another one. So the Fast Refresh
+ * wrapper hands the router the next exports, and a loader the development
+ * route table tagged with `ufHotFile` (see `routesModuleSource` in
+ * `@uniflowed/vite`) answers with those. Empty outside development: nothing
+ * else writes to it.
+ */
+const hotModules: Map<string, mixed> = new Map();
+
+/** Answer `file`'s loader with `exports` from now on. Development only. */
+export function replaceHotModule(file: string, exports: mixed): void {
+  hotModules.set(file, exports);
+}
+
+/**
+ * Keep the replaced modules a new route table still loads, and forget the
+ * rest. `files` is the table's `hotFiles`; `null`, from a table that carries
+ * none, forgets everything.
+ *
+ * Kept rather than forgotten, because the new table's `import()` names the
+ * module under a URL of its own, and a second evaluation of `$page.js` is a
+ * second `Page` React has never seen: it would remount the page and throw away
+ * the state the update was meant to keep. The replaced exports *are* the
+ * module's newest version — every edit to a route module goes through
+ * `replaceHotModule` — so answering with them is answering with the file.
+ */
+export function retainHotModules(files: ?$ReadOnlySet<string>): void {
+  for (const file of [...hotModules.keys()]) {
+    if (files == null || !files.has(file)) {
+      hotModules.delete(file);
+    }
+  }
+}
+
 export function loadOnce<T>(load: () => Promise<T>): Promise<T> {
+  if (hotModules.size > 0) {
+    // $FlowFixMe[prop-missing] a development table's loaders carry their module's key.
+    const file: mixed = load.ufHotFile;
+    if (typeof file === "string" && hotModules.has(file)) {
+      // $FlowFixMe[incompatible-type] the module this loader imports, replaced.
+      return Promise.resolve(hotModules.get(file));
+    }
+  }
   let pending = moduleCache.get(load);
   if (pending == null) {
     pending = load();

package/internal/runtime.js

@@ -114,7 +114,9 @@ import {
   interceptingRoutes,
   loadOnce,
   pageSearchParams,
+  replaceHotModule,
   resolveFailure,
+  retainHotModules,
   resolveInterception,
   resolveMatch,
 } from "./resolve.js";
@@ -412,6 +414,96 @@ hook useMountedRouter(router: Router, showNotFound: ShowNotFound): void {
   });
 }
 
+// ---------------------------------------------------------------------------
+// Hot updates, in development
+// ---------------------------------------------------------------------------
+//
+// A dev server edit used to reach this router one way: a reload, which renders
+// the edit and discards every `useState`, scroll position and open dialog on
+// the page. Three kinds of edit now arrive as a render instead, and all three
+// end in `refreshForHotUpdate` — the mounted router's own `refresh()`, which
+// resolves the URL on screen again under the components React already has, so
+// state survives wherever the tree still has the same shape:
+//
+//   * a server component, under React Server Components: `@uniflowed/vite`
+//     sends `uf:refresh`, and the payload is fetched again;
+//   * a route file added or removed: a new `virtual:uf/routes`, installed by
+//     `replaceRoutesForHotUpdate`, or `uf:refresh` for the server's table;
+//   * a route module's loader, metadata or other data export: its Fast Refresh
+//     wrapper calls the hook `acceptHotRouteModules` installs, the next exports
+//     answer that module's loader from then on, and the loader runs again.
+//
+// `@uniflowed/vite` generates the calls into `virtual:uf/client` for a dev
+// server and never for a build, so none of this is reached in production.
+
+/**
+ * Long enough to land after Fast Refresh's own 16 ms batch, so React has the
+ * new component families before the router renders with them, and to collapse
+ * one save that touched several modules into one refresh.
+ */
+const HOT_REFRESH_DELAY = 32;
+
+let hotRefreshTimer: TimeoutID | null = null;
+
+/**
+ * Render the URL on screen again because the dev server replaced something
+ * under it. Reloads the document when no router is mounted — a page that ships
+ * no client page, say — or when the refresh itself fails, because a reload is
+ * always right and the render only usually is.
+ */
+export function refreshForHotUpdate(): void {
+  if (!isBrowser()) {
+    return;
+  }
+  if (hotRefreshTimer != null) {
+    clearTimeout(hotRefreshTimer);
+  }
+  hotRefreshTimer = setTimeout(() => {
+    hotRefreshTimer = null;
+    const router = mountedRouter;
+    if (router == null) {
+      window.location.reload();
+      return;
+    }
+    router.refresh().catch((error) => {
+      // Said before the document goes, so the console that is about to be
+      // cleared says why a hot update became a reload.
+      console.warn("[uf] could not render the hot update in place, reloading:", error);
+      window.location.reload();
+    });
+  }, HOT_REFRESH_DELAY);
+}
+
+/**
+ * Install a route table the dev server rebuilt, and render the URL on screen
+ * against it. `table` is the new `virtual:uf/routes` itself; the modules
+ * replaced under the old table stay replaced unless its `hotFiles` no longer
+ * names them. See `retainHotModules` for why.
+ */
+export function replaceRoutesForHotUpdate(
+  table: $ReadOnly<{ ...RouteTable, hotFiles?: $ReadOnlySet<string>, ... }>,
+): void {
+  installRoutes({ routes: table.routes, notFound: table.notFound, errors: table.errors });
+  retainHotModules(table.hotFiles);
+  refreshForHotUpdate();
+}
+
+/**
+ * Let a route module's Fast Refresh wrapper hand this router its next exports.
+ * See `addRefreshWrapper` in `@uniflowed/vite`, which calls it as
+ * `window.__UF_HOT_ROUTE__(file, exports)` with the module's path from the
+ * project root.
+ */
+export function acceptHotRouteModules(): void {
+  if (!isBrowser()) {
+    return;
+  }
+  window.__UF_HOT_ROUTE__ = (file: string, exports: mixed) => {
+    replaceHotModule(file, exports);
+    refreshForHotUpdate();
+  };
+}
+
 /**
  * Show the page a loader's `notFound()` would have shown for the URL on screen,
  * because something below the route's error boundary threw `NotFoundError`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/router",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "The file-system router for Flow React applications: matching, layouts, loaders, navigation, server rendering and hydration.",
   "type": "module",
   "license": "MIT",
@@ -73,8 +73,8 @@
     }
   },
   "dependencies": {
-    "@uniflowed/hooks": "0.13.1",
-    "@uniflowed/server": "0.13.1",
-    "@uniflowed/validator": "0.13.1"
+    "@uniflowed/hooks": "0.14.0",
+    "@uniflowed/server": "0.14.0",
+    "@uniflowed/validator": "0.14.0"
   }
 }

package/rsc-client.js

@@ -45,6 +45,10 @@ import {
 import { hydrationOptions } from "./internal/hydrate-options.js";
 import { readFormState } from "./internal/form-action.js";
 
+// What `virtual:uf/client` calls in development when a server component
+// changed; see "Hot updates" in `./internal/runtime.js`.
+export { refreshForHotUpdate } from "./internal/runtime.js";
+
 /**
  * Hydrate a document React Server Components rendered.
  *