Allow configuration of the manifest path

Author: brophdawg11

.changeset/angry-students-pay.md

@@ -7,3 +7,5 @@ Add new `routeDiscovery` `react-router.config.ts` option to disable Lazy Route D
 
 - The default value is `routeDiscovery: "lazy"`
 - Setting `routeDiscovery: "initial"` will disable Lazy Route Discovery and send up all routes in the manifest on initial document load
+- There is also an object version of the config which allows you to customize the manifest path when using `lazy`
+  - `routeDiscovery: { mode: "lazy", manifestPath: "/custom-manifest" }`

integration/fog-of-war-test.ts

@@ -1409,6 +1409,52 @@ test.describe("Fog of War", () => {
     await page.waitForSelector("#a-index");
   });
 
+  test("allows configuration of the manifest path", async ({ page }) => {
+    let fixture = await createFixture({
+      files: {
+        ...getFiles(),
+        "react-router.config.ts": reactRouterConfig({
+          routeDiscovery: { manifestPath: "/custom-manifest" },
+        }),
+      },
+    });
+    let appFixture = await createAppFixture(fixture);
+    let app = new PlaywrightFixture(appFixture, page);
+
+    let wrongManifestRequests: string[] = [];
+    let manifestRequests: string[] = [];
+    page.on("request", (req) => {
+      if (req.url().includes("/__manifest")) {
+        wrongManifestRequests.push(req.url());
+      }
+      if (req.url().includes("/custom-manifest")) {
+        manifestRequests.push(req.url());
+      }
+    });
+
+    await app.goto("/", true);
+    expect(
+      await page.evaluate(() =>
+        Object.keys((window as any).__reactRouterManifest.routes)
+      )
+    ).toEqual(["root", "routes/_index", "routes/a"]);
+    expect(manifestRequests).toEqual([
+      expect.stringMatching(/\/custom-manifest\?p=%2F&p=%2Fa&version=/),
+    ]);
+    manifestRequests = [];
+
+    await app.clickLink("/a");
+    await page.waitForSelector("#a");
+    expect(await app.getHtml("#a")).toBe(`<h1 id="a">A: A LOADER</h1>`);
+    // Wait for eager discovery to kick off
+    await new Promise((r) => setTimeout(r, 500));
+    expect(manifestRequests).toEqual([
+      expect.stringMatching(/\/custom-manifest\?p=%2Fa%2Fb&version=/),
+    ]);
+
+    expect(wrongManifestRequests).toEqual([]);
+  });
+
   test.describe("routeDiscovery=initial", () => {
     test("loads full manifest on initial load", async ({ page }) => {
       let fixture = await createFixture({

integration/helpers/vite.ts

@@ -42,7 +42,14 @@ export const reactRouterConfig = ({
   >["unstable_splitRouteModules"];
   viteEnvironmentApi?: boolean;
   middleware?: boolean;
-  routeDiscovery?: "initial" | "lazy";
+  routeDiscovery?:
+    | "initial"
+    | "lazy"
+    | {
+        mode?: "lazy";
+        manifestPath: string;
+      }
+    | { mode: "initial" };
 }) => {
   let config: Config = {
     ssr,

packages/react-router-dev/config/config.ts

@@ -159,12 +159,28 @@ export type ReactRouterConfig = {
    */
   presets?: Array<Preset>;
   /**
-   * Control the "Lazy Route Discovery" behavior.  By default, this resolves to
-   * `lazy` which will lazily discover routes as the user navigates around your
-   * application.  You can set this to `initial` to opt-out of this behavior and
-   * load all routes with the initial HTML document load.
+   * Control the "Lazy Route Discovery" behavior.
+   *
+   * - `routeDiscovery.mode`: By default, this resolves to `lazy` which will
+   *   lazily discover routes as the user navigates around your application.
+   *   You can set this to `initial` to opt-out of this behavior and load all
+   *   routes with the initial HTML document load.
+   * - `routeDiscovery.manifestPath`: The path to serve the manifest file from.
+   *    Only applies to `mode: "lazy"` and defaults to `/__manifest`.
+   *
+   * If you do not need to control the manifest, you can specify the mode
+   * directly on the `routeDiscovery` config.
    */
-  routeDiscovery?: "lazy" | "initial";
+  routeDiscovery?:
+    | "lazy"
+    | "initial"
+    | {
+        mode?: "lazy"; // Can only adjust the manifest path in `lazy` mode
+        manifestPath: string;
+      }
+    | {
+        mode: "initial";
+      };
   /**
    * The file name of the server build output. This file
    * should end in a `.js` extension and should be deployed to your server.
@@ -218,7 +234,10 @@ export type ResolvedReactRouterConfig = Readonly<{
    * application.  You can set this to `initial` to opt-out of this behavior and
    * load all routes with the initial HTML document load.
    */
-  routeDiscovery: ReactRouterConfig["routeDiscovery"];
+  routeDiscovery: {
+    mode: "lazy" | "initial";
+    manifestPath: string;
+  };
   /**
    * An object of all available routes, keyed by route id.
    */
@@ -397,7 +416,6 @@ async function resolveConfig({
   let defaults = {
     basename: "/",
     buildDirectory: "build",
-    routeDiscovery: "lazy",
     serverBuildFile: "index.js",
     serverModuleFormat: "esm",
     ssr: true,
@@ -414,7 +432,7 @@ async function resolveConfig({
     buildDirectory: userBuildDirectory,
     buildEnd,
     prerender,
-    routeDiscovery,
+    routeDiscovery: userRouteDiscovery,
     serverBuildFile,
     serverBundles,
     serverModuleFormat,
@@ -441,17 +459,43 @@ async function resolveConfig({
     );
   }
 
-  if (routeDiscovery === "lazy" && !ssr) {
-    if (userAndPresetConfigs.routeDiscovery === "lazy") {
-      // If the user set "lazy" and `ssr:false`, then it's an invalid config
-      // and we want to fail the build
+  let routeDiscovery: ResolvedReactRouterConfig["routeDiscovery"] = {
+    mode: "lazy",
+    manifestPath: "/__manifest",
+  };
+
+  if (userRouteDiscovery == null) {
+    if (!ssr) {
+      // No FOW when SSR is disabled
+      routeDiscovery.mode = "initial";
+    } else {
+      // no-op - use defaults
+    }
+  } else if (
+    userRouteDiscovery === "initial" ||
+    (typeof userRouteDiscovery === "object" &&
+      userRouteDiscovery.mode === "initial")
+  ) {
+    routeDiscovery.mode = "initial";
+  } else {
+    if (!ssr) {
       return err(
-        'The `routeDiscovery` config cannot be set to "lazy" when setting `ssr:false`'
+        'The `routeDiscovery` config must be left unset or set to "initial" ' +
+          "when setting `ssr:false`"
       );
-    } else {
-      // But if the user didn't specify, then we want to default to "initial"
-      // when SSR is disabled
-      routeDiscovery = "initial";
+    }
+    if (typeof userRouteDiscovery === "object") {
+      if (
+        userRouteDiscovery.manifestPath != null &&
+        !userRouteDiscovery.manifestPath.startsWith("/")
+      ) {
+        return err(
+          "The `routeDiscovery.manifestPath` config must be a root-relative " +
+            'pathname beginning with a slash (i.e., "/__manifest")'
+        );
+      }
+      routeDiscovery.manifestPath =
+        userRouteDiscovery.manifestPath ?? "/__manifest";
     }
   }
 

packages/react-router/lib/dom/ssr/components.tsx

@@ -647,7 +647,7 @@ export function Scripts(props: ScriptsProps) {
     useFrameworkContext();
   let { router, static: isStatic, staticContext } = useDataRouterContext();
   let { matches: routerMatches } = useDataRouterStateContext();
-  let enableFogOfWar = routeDiscovery === "lazy";
+  let enableFogOfWar = routeDiscovery.mode === "lazy";
 
   // Let <ServerRouter> know that we hydrated and we should render the single
   // fetch streaming scripts

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

@@ -73,7 +73,7 @@ export function getPatchRoutesOnNavigationFunction(
   isSpaMode: boolean,
   basename: string | undefined
 ): PatchRoutesOnNavigationFunction | undefined {
-  if (routeDiscovery !== "lazy") {
+  if (routeDiscovery.mode !== "lazy") {
     return undefined;
   }
 
@@ -89,6 +89,7 @@ export function getPatchRoutesOnNavigationFunction(
       ssr,
       isSpaMode,
       basename,
+      routeDiscovery.manifestPath,
       patch,
       signal
     );
@@ -105,7 +106,10 @@ export function useFogOFWarDiscovery(
 ) {
   React.useEffect(() => {
     // Don't prefetch if not enabled or if the user has `saveData` enabled
-    if (routeDiscovery !== "lazy" || navigator.connection?.saveData === true) {
+    if (
+      routeDiscovery.mode !== "lazy" ||
+      navigator.connection?.saveData === true
+    ) {
       return;
     }
 
@@ -156,6 +160,7 @@ export function useFogOFWarDiscovery(
           ssr,
           isSpaMode,
           router.basename,
+          routeDiscovery.manifestPath,
           router.patchRoutes
         );
       } catch (e) {
@@ -193,13 +198,13 @@ export async function fetchAndApplyManifestPatches(
   ssr: boolean,
   isSpaMode: boolean,
   basename: string | undefined,
+  _manifestPath: string,
   patchRoutes: DataRouter["patchRoutes"],
   signal?: AbortSignal
 ): Promise<void> {
-  let manifestPath = `${basename != null ? basename : "/"}/__manifest`.replace(
-    /\/+/g,
-    "/"
-  );
+  let manifestPath = `${
+    basename != null ? basename : "/"
+  }${_manifestPath}`.replace(/\/+/g, "/");
   let url = new URL(manifestPath, window.location.origin);
   paths.sort().forEach((path) => url.searchParams.append("p", path));
   url.searchParams.set("version", manifest.version);

packages/react-router/lib/dom/ssr/routes-test-stub.tsx

@@ -113,7 +113,7 @@ export function createRoutesStub(
         routeModules: {},
         ssr: false,
         isSpaMode: false,
-        routeDiscovery: "lazy",
+        routeDiscovery: { mode: "lazy", manifestPath: "/__manifest" },
       };
 
       // Update the routes to include context in the loader/action and populate

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

@@ -37,7 +37,10 @@ export interface ServerBuild {
    */
   isSpaMode: boolean;
   prerender: string[];
-  routeDiscovery: "lazy" | "initial";
+  routeDiscovery: {
+    mode: "lazy" | "initial";
+    manifestPath: string;
+  };
 }
 
 export interface HandleDocumentRequestFunction {

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

@@ -199,7 +199,11 @@ export const createRequestHandler: CreateRequestHandlerFunction = (
     }
 
     // Manifest request for fog of war
-    let manifestUrl = `${normalizedBasename}/__manifest`.replace(/\/+/g, "/");
+    let manifestUrl =
+      `${normalizedBasename}${_build.routeDiscovery.manifestPath}`.replace(
+        /\/+/g,
+        "/"
+      );
     if (url.pathname === manifestUrl) {
       try {
         let res = await handleManifestRequest(_build, routes, url);