Programmatic Lazy Route Discovery

[brettburley]

Problem

In framework mode with routeDiscovery: { mode: "lazy" }, React Router discovers missing routes via /__manifest mostly by scanning <a data-discover> / <form data-discover> (i.e. Link/Form-driven). Apps with button-driven flows (wizards, command palettes, programmatic navigate) can’t easily pre-discover needed routes without rendering fake/hidden links.

This can cause manifest waterfalls or force hard navigations when versions are deployed, risking loss of in-memory state (e.g. multi-step forms) or expensive re-hydration.

Proposal

Add a public API to programmatically discover routes (fetch/apply manifest patches) for a set of paths, without rendering Link tags.

API sketch

// Router instance
interface Router {
  discoverRoutes(
    paths: Array<string | To>,
    opts?: { signal?: AbortSignal }
  ): Promise<DiscoveryResult>;
}

type DiscoveryResult =
  | { type: "success"; discovered: string[]; skipped: string[] }
  | { type: "version-mismatch" }
  | { type: "aborted" };

// Hook wrapper
function useRouteDiscovery(): {
  discoverRoutes: (
    paths: Array<string | To>,
    opts?: { signal?: AbortSignal }
  ) => Promise<DiscoveryResult>;
  mode: "lazy" | "initial" | null;
};

• Batches requests, dedupes already-known paths, supports cancellation.
• Status is returned so that it can be appropriately handled (e.g. refresh the page eagerly, or show a banner that the page must be reloaded to continue, etc.).
• No asset/data prefetch implied (discovery only). Prefetch might work if you use it in concert with PrefetchPageLinks?

Example (multi-step wizard)

function CheckoutWizard() {
  let { discoverRoutes, mode } = useRouteDiscovery();
  let [blocked, setBlocked] = useState(false);

  useEffect(() => {
    if (mode !== "lazy") return;
    let ac = new AbortController();

    discoverRoutes(
      ["/checkout/shipping", "/checkout/billing", "/checkout/review"],
      { signal: ac.signal }
    ).then((result) => {
      if (result.type === "version-mismatch") {
        // A new version has been deployed. If the user continues this
        // flow, navigating to a later step will trigger a full page
        // reload — losing all in-memory form state. Better to block
        // entry now and prompt a refresh than to lose data mid-flow.
        setBlocked(true);
      }
    });

    return () => ac.abort();
  }, [discoverRoutes, mode]);

  if (blocked) {
    return (
      <div>
        <p>A new version is available. Please refresh to continue.</p>
        <button onClick={() => window.location.reload()}>Refresh</button>
      </div>
    );
  }

  return <WizardWithButtons />;
}

Considerations

A declarative version of the hook might be useful for a lot of contexts, e.g.:

function CheckoutWizard() {
  let discovery = useDiscoverRoutes([
    "/checkout/shipping",
    "/checkout/billing",
    "/checkout/review",
  ]);

  if (discovery.state === "discovering") return <Spinner />;

  if (discovery.state === "version-mismatch") {
    return (
      <div>
        <p>A new version is available. Please refresh to continue.</p>
        <button onClick={() => window.location.reload()}>Refresh</button>
      </div>
    );
  }

  return <WizardWithButtons />;
}

[brophdawg11]

This is implemented in PR #15602: unstable_useRouteDiscovery().discoverRoutes(paths, { signal }) discovers selected paths without rendering links or navigating, with success, version-mismatch, and aborted results. It is opt-in for conventional Framework Mode.

Authored by an AI agent on behalf of @brophdawg11