Detect lazy route discovery manifest version mismatches and trigger reloads

.changeset/real-adults-protect.md

@@ -0,0 +1,9 @@
+---
+"react-router": minor
+---
+
+Add `fetcherKey` as a parameter to `patchRoutesOnNavigation`
+
+- In framework mode, Lazy Route Discovery will now detect manifest version mismatches after a new deploy
+- On navigations to undiscovered routes, this mismatch will trigger a document reload of the destination path
+- On `fetcher` calls to undiscovered routes, this mismatch will trigger a document reload of the current path

packages/react-router/lib/dom/ssr/fog-of-war.ts

@@ -78,12 +78,13 @@ export function getPatchRoutesOnNavigationFunction(
     return undefined;
   }
 
-  return async ({ path, patch, signal }) => {
+  return async ({ path, patch, signal, fetcherKey }) => {
     if (discoveredPaths.has(path)) {
       return;
     }
     await fetchAndApplyManifestPatches(
       [path],
+      fetcherKey ? window.location.href : path,
       manifest,
       routeModules,
       ssr,
@@ -149,6 +150,7 @@ export function useFogOFWarDiscovery(
       try {
         await fetchAndApplyManifestPatches(
           lazyPaths,
+          null,
           manifest,
           routeModules,
           ssr,
@@ -181,8 +183,11 @@ export function useFogOFWarDiscovery(
   }, [ssr, isSpaMode, manifest, routeModules, router]);
 }
 
+const MANIFEST_VERSION_STORAGE_KEY = "react-router-manifest-version";
+
 export async function fetchAndApplyManifestPatches(
   paths: string[],
+  errorReloadPath: string | null,
   manifest: AssetsManifest,
   routeModules: RouteModules,
   ssr: boolean,
@@ -213,10 +218,48 @@ export async function fetchAndApplyManifestPatches(
 
     if (!res.ok) {
       throw new Error(`${res.status} ${res.statusText}`);
+    } else if (
+      res.status === 204 &&
+      res.headers.has("X-Remix-Reload-Document")
+    ) {
+      if (!errorReloadPath) {
+        // No-op during eager route discovery so we will trigger a hard reload
+        // of the destination during the next navigation instead of reloading
+        // while the user is sitting on the current page.  Slightly more
+        // disruptive on fetcher calls because we reload the current page, but
+        // it's better than the `React.useContext` error that occurs without
+        // this detection.
+        console.warn(
+          "Detected a manifest version mismatch during eager route discovery. " +
+            "The next navigation/fetch to an undiscovered route will result in " +
+            "a new document navigation to sync up with the latest manifest."
+        );
+        return;
+      }
+
+      // This will hard reload the destination path on navigations, or the
+      // current path on fetcher calls
+      if (
+        sessionStorage.getItem(MANIFEST_VERSION_STORAGE_KEY) ===
+        manifest.version
+      ) {
+        // We've already tried fixing for this version, don' try again to
+        // avoid loops - just let this navigation/fetch 404
+        console.error(
+          "Unable to discover routes due to manifest version mismatch."
+        );
+        return;
+      }
+
+      sessionStorage.setItem(MANIFEST_VERSION_STORAGE_KEY, manifest.version);
+      window.location.href = errorReloadPath;
+      throw new Error("Detected manifest version mismatch, reloading...");
     } else if (res.status >= 400) {
       throw new Error(await res.text());
     }
 
+    // Reset loop-detection on a successful response
+    sessionStorage.removeItem(MANIFEST_VERSION_STORAGE_KEY);
     serverPatches = (await res.json()) as AssetsManifest["routes"];
   } catch (e) {
     if (signal?.aborted) return;

packages/react-router/lib/router/router.ts

@@ -2225,7 +2225,8 @@ export function createRouter(init: RouterInit): Router {
       let discoverResult = await discoverRoutes(
         requestMatches,
         path,
-        fetchRequest.signal
+        fetchRequest.signal,
+        key
       );
 
       if (discoverResult.type === "aborted") {
@@ -2509,7 +2510,8 @@ export function createRouter(init: RouterInit): Router {
       let discoverResult = await discoverRoutes(
         matches,
         path,
-        fetchRequest.signal
+        fetchRequest.signal,
+        key
       );
 
       if (discoverResult.type === "aborted") {
@@ -3168,7 +3170,8 @@ export function createRouter(init: RouterInit): Router {
   async function discoverRoutes(
     matches: AgnosticDataRouteMatch[],
     pathname: string,
-    signal: AbortSignal
+    signal: AbortSignal,
+    fetcherKey?: string
   ): Promise<DiscoverRoutesResult> {
     if (!patchRoutesOnNavigationImpl) {
       return { type: "success", matches };
@@ -3184,6 +3187,7 @@ export function createRouter(init: RouterInit): Router {
           signal,
           path: pathname,
           matches: partialMatches,
+          fetcherKey,
           patch: (routeId, children) => {
             if (signal.aborted) return;
             patchRoutesImpl(

packages/react-router/lib/router/utils.ts

@@ -285,6 +285,7 @@ export type AgnosticPatchRoutesOnNavigationFunctionArgs<
   signal: AbortSignal;
   path: string;
   matches: M[];
+  fetcherKey: string | undefined;
   patch: (routeId: string | null, children: O[]) => void;
 };
 

packages/react-router/lib/server-runtime/server.ts

@@ -296,6 +296,15 @@ async function handleManifestRequest(
   routes: ServerRoute[],
   url: URL
 ) {
+  if (build.assets.version !== url.searchParams.get("version")) {
+    return new Response(null, {
+      status: 204,
+      headers: {
+        "X-Remix-Reload-Document": "true",
+      },
+    });
+  }
+
   let patches: Record<string, EntryRoute> = {};
 
   if (url.searchParams.has("p")) {