Custom cache keys for lazy route discovery

[brophdawg11]

Summary

Add an optional client-side callback to <HydratedRouter> that allows applications to customize how successful lazy route discovery requests are cached.

<HydratedRouter
  unstable_getRouteDiscoveryCacheKey={({ pathname, pattern }) => {
    if (pattern === "/product/:id") {
      return "product";
    }
  }}
/>

After React Router successfully discovers /product/a, it records the "product" cache key. If /product/b subsequently matches the currently known /product/:id route, React Router can use the cached key and avoid another /__manifest request.

This is an opt-in assertion made by the application. Returning the same key for multiple pathnames asserts that discovering any one of those pathnames provides enough route manifest information to correctly match every pathname using that key.

Motivation

Lazy route discovery initially sends only the routes required for the current document. As users navigate, React Router requests additional route metadata from /__manifest.

Dynamic routes create an unavoidable ambiguity:

route("product/:id", "./product.tsx");
route("product/b", "./special-product.tsx");

Once /product/a has been discovered, the client knows about /product/:id. When navigating to /product/b, that dynamic route matches locally, but React Router cannot assume it is the correct match. An undiscovered static route such as /product/b would rank higher.

React Router therefore performs another manifest request whenever the current match contains dynamic or splat parameters.

This is the correct default, but it can produce redundant requests for applications that know more about their route space. For example, an application may know that:

• /product/:id has no static exceptions;
• all product identifiers are handled identically;
• particular static exceptions can be explicitly excluded;
• repeated manifest requests are expensive at the application’s scale.

We want to let those applications suppress redundant requests without adding route analysis or additional CPU work to the publicly accessible /__manifest endpoint.

Proposed API

type RouteDiscoveryCacheKeyFunction = (args: {
  pathname: string;
  pattern: string;
}) => string | undefined;

interface HydratedRouterProps {
  unstable_getRouteDiscoveryCacheKey?: RouteDiscoveryCacheKeyFunction;
}

Example:

import { HydratedRouter } from "react-router/dom";
import { hydrateRoot } from "react-dom/client";

hydrateRoot(
  document,
  <HydratedRouter
    unstable_getRouteDiscoveryCacheKey={({ pattern }) => {
      if (pattern === "/product/:id") {
        return "product";
      }
    }}
  />,
);

The callback receives:

• pathname: The concrete pathname being discovered, such as /product/a.
• pattern: The currently matched, uninterpolated route pattern, such as /product/:id.

Returning a string provides a custom discovery cache key. Returning undefined retains the existing exact-path caching behavior.

The callback is synchronous and client-only.

Semantics

Successful discovery

Suppose the client does not yet know about /product/:id.

1. The user navigates to /product/a.
2. The client cannot match the pathname and requests /__manifest.
3. The response adds /product/:id to the client manifest.
4. React Router rematches /product/a and obtains the pattern /product/:id.
5. The callback returns "product".
6. React Router records "product" as discovered.

Later:

1. The user navigates to /product/b.
2. The known /product/:id route matches.
3. The callback returns "product".
4. Because "product" is already discovered, React Router skips the manifest request.
5. Navigation continues using the known route.

Initial document matches

Routes included in the initial server-rendered manifest are authoritative for that document request. Their custom cache keys are seeded during hydration.

If the initial document is /product/a, the application can navigate to /product/b without first making a client-side manifest request.

Eager link discovery

The same cache applies to eager discovery from rendered links and forms.

After "product" has been discovered, rendering this link does not make another manifest request:

<Link to="/product/b">Product B</Link>

When the callback is not configured, eager discovery retains its existing behavior and does not perform additional route matching.

Failed or interrupted discovery

A custom key is recorded only after successful discovery.

The key is not recorded when:

• the request fails;
• the request is aborted;
• a manifest version mismatch requires a document reload;
• eager discovery is skipped because the request URL exceeds the URL limit.

Cache lifetime

Custom keys are held in the same in-memory, page-lifetime cache used for discovered pathnames. They are not persisted across document reloads.

Correctness contract

This API intentionally transfers part of the route-discovery correctness responsibility to the application.

Returning the same cache key for multiple pathnames asserts that the currently known route manifest is sufficient to correctly match every pathname using that key.

Consider:

route("product/:id", "./product.tsx");
route("product/b", "./special-product.tsx");

With this callback:

unstable_getRouteDiscoveryCacheKey={({ pattern }) => {
  if (pattern === "/product/:id") {
    return "product";
  }
}}

The following can occur:

1. /product/a discovers /product/:id.
2. "product" is cached.
3. /product/b locally matches /product/:id.
4. The manifest request is skipped.
5. The client never discovers the higher-ranked /product/b route.

The callback must account for known exceptions:

unstable_getRouteDiscoveryCacheKey={({ pathname, pattern }) => {
  if (
    pattern === "/product/:id" &&
    pathname !== "/product/b"
  ) {
    return "product";
  }
}}

Returning undefined for /product/b causes it to use normal pathname-based discovery. Once the static route has been discovered, it will match as /product/b rather than /product/:id.

This is similar to APIs such as shouldRevalidate: React Router provides a correct default, while applications may opt into a more aggressive optimization when they can guarantee its assumptions.

Why include pathname?

A callback receiving only the matched pattern is simpler:

function getCacheKey(pattern: string): string | undefined;

However, the known client route tree may produce /product/:id for both /product/a and an undiscovered static /product/b.

Providing the concrete pathname lets applications preserve discovery for known exceptions:

if (pattern === "/product/:id" && pathname !== "/product/b") {
  return "product";
}

It also supports applications whose grouping rules depend on tenant prefixes, locales, or other concrete pathname segments.

Server behavior

This proposal does not change /__manifest.

In particular, it does not:

• send cache keys to the server;
• ask the endpoint to expand a route group;
• analyze competing routes;
• add new response metadata;
• add additional route matching at request time.

The endpoint continues receiving concrete paths and returning their matched route manifest entries.

All custom cache-key behavior happens on the client after the normal response has been applied.

Performance

The intended benefit is avoiding repeated network requests and server-side route matching for dynamic paths that the application knows are equivalent.

When the callback is absent, there should be no additional matching or callback overhead.

When configured:

• on-demand navigation uses matches already computed by the router;
• eager link discovery may locally match rendered destinations against the currently known route tree;
• the callback itself is expected to be inexpensive and deterministic;
• /__manifest receives no additional work.

Scope

The initial proposal applies to conventional Framework Mode through <HydratedRouter>.

It does not initially apply to:

• Declarative Mode;
• Data Mode applications using their own patchRoutesOnNavigation;
• RSC Data Mode;
• RSC Framework Mode through unstable_RSCHydratedRouter.

RSC Framework parity can be considered separately once the API semantics have been validated.

Alternatives considered

A manifestGroup prop on links

<Link to="/product/a" manifestGroup="product" />

This is locally explicit but makes route-space knowledge a property of individual links. It would need to be repeated across the application and would not naturally cover programmatic navigation, redirects, forms, fetchers, or initial document loads.

It also cannot guarantee that the first group member loads all other routes belonging to that group.

A function in react-router.config.ts

function identifyRouteGroup(pathname: string) {
  if (pathname.startsWith("/product/")) {
    return "product";
  }
}

Framework configuration is used during the build and on the server, while this optimization needs to execute in the browser. Arbitrary functions cannot be serialized safely into the client build without introducing an additional module or bundling contract.

Running the function on /__manifest would also add user-defined work to a public endpoint that is already performance-sensitive.

Declarative build-time route groups

routeDiscovery: {
  groups: [{ id: "product", prefix: "/product" }],
}

The compiler could precompute all route IDs belonging to each group and the endpoint could return the entire group on first access.

This can provide a stronger correctness guarantee, but it requires build-manifest changes, server protocol changes, client/server group synchronization, and potentially much larger manifest responses.

It also solves a different problem: eagerly loading a group instead of allowing applications to assert that the current manifest is already sufficient.

Automatically discovering competing routes

React Router could inspect flattened route branches and include every route that might outrank a newly discovered dynamic route.

Although the flattened branches contain ranking metadata, determining whether two route patterns overlap requires symbolic route-pattern analysis. Handling optional segments, splats, pathless layouts, partial parameters, case sensitivity, and equal-ranked route ordering adds substantial complexity.

Doing this work at request time would make /__manifest more expensive. Precomputing it would still add build complexity and could produce large competition sets.

Shipping the full route topology

React Router could send a lightweight route-matching tree up front while continuing to lazy-load module and asset metadata.

This removes the ambiguity entirely, but adds initial payload proportional to the total route count and weakens the primary benefit of lazy route discovery.

Prototype

A proof of concept implements:

• unstable_getRouteDiscoveryCacheKey on <HydratedRouter>;
• normalized matched patterns such as /product/:id;
• cache lookup during navigation;
• cache lookup during eager link and form discovery;
• cache seeding from initial hydration matches;
• cache insertion only after successful manifest discovery;
• no additional work when the callback is absent;
• no changes to /__manifest.

The prototype verifies that after discovering /product/a, rendering or navigating to /product/b does not make another manifest request when both resolve to the "product" cache key.

Open questions

1. Is unstable_getRouteDiscoveryCacheKey the clearest name, or would unstable_getManifestCacheKey better communicate its purpose?
2. Should the callback receive { pathname, pattern }, only pattern, or the full partial matches?
3. Should initial document matches seed custom keys, or should a client manifest request be required first?
4. Should custom keys apply to splat routes?
5. Should React Router impose a separate maximum size for the custom-key cache?
6. Should exceptions be easier to express than checking pathname manually?
7. Should the callback be invoked only for matches containing dynamic or splat parameters?
8. Should RSC Framework support be required before introducing the API?
9. Is the correctness footgun acceptable for an explicitly unstable performance API?

Request for feedback

The main questions are:

• Do large applications encounter enough repeated dynamic-path discovery requests for this optimization to be useful?
• Is the user-owned correctness assertion understandable?
• Is a client-only callback preferable to declarative build-time route groups?
• Are there important navigation or eager-discovery cases this proposal does not cover?