From 8ea019a5dc27997815f898350a0c6cdde081f905 Mon Sep 17 00:00:00 2001 From: Brooks Lybrand Date: Fri, 27 Jun 2025 14:26:44 -0500 Subject: [PATCH] docs: add Lazy Route Discovery doc (#13891) * Update react-router.config.ts * add lazy route discovery doc * Update react-router.config.ts.md * Remove incorrect performance point --------- Co-authored-by: Matt Brophy --- .../react-router.config.ts.md | 32 ++++++++ docs/explanation/lazy-route-discovery.md | 77 +++++++++++++++++++ 2 files changed, 109 insertions(+) create mode 100644 docs/explanation/lazy-route-discovery.md diff --git a/docs/api/framework-conventions/react-router.config.ts.md b/docs/api/framework-conventions/react-router.config.ts.md index 60866f44c3..c87450e942 100644 --- a/docs/api/framework-conventions/react-router.config.ts.md +++ b/docs/api/framework-conventions/react-router.config.ts.md @@ -120,6 +120,37 @@ export default { } satisfies Config; ``` +### `routeDiscovery` + +Configure how routes are discovered and loaded by the client. Defaults to `mode: "lazy"` with `manifestPath: "/__manifest"`. + +**Options:** + +- `mode: "lazy"` - Routes are discovered as the user navigates (default) + - `manifestPath` - Custom path for manifest requests when using `lazy` mode +- `mode: "initial"` - All routes are included in the initial manifest + +```tsx filename=react-router.config.ts +export default { + // Enable lazy route discovery (default) + routeDiscovery: { + mode: "lazy", + manifestPath: "/__manifest", + }, + + // Use a custom manifest path + routeDiscovery: { + mode: "lazy", + manifestPath: "/custom-manifest", + }, + + // Disable lazy discovery and include all routes initially + routeDiscovery: { mode: "initial" }, +} satisfies Config; +``` + +See [Lazy Route Discovery][lazy-route-discovery] for more information. + ### `serverBuildFile` The file name of the server build output. This file should end in a `.js` extension and should be deployed to your server. Defaults to `"index.js"`. @@ -176,3 +207,4 @@ export default { [server-bundles]: ../../how-to/server-bundles [pre-rendering]: ../../how-to/pre-rendering [spa-mode]: ../../how-to/spa +[lazy-route-discovery]: ../../explanation/lazy-route-discovery diff --git a/docs/explanation/lazy-route-discovery.md b/docs/explanation/lazy-route-discovery.md new file mode 100644 index 0000000000..b3491aaa97 --- /dev/null +++ b/docs/explanation/lazy-route-discovery.md @@ -0,0 +1,77 @@ +--- +title: Lazy Route Discovery +--- + +# Lazy Route Discovery + +[MODES: framework] + +## Overview + +Lazy Route Discovery is a performance optimization that loads route information progressively as users navigate through your application, rather than loading the complete route manifest upfront. + +With Lazy Route Discovery enabled (the default), React Router sends only the routes needed for the initial server-side render in the manifest. As users navigate to new parts of your application, additional route information is fetched dynamically and added to the client-side manifest. + +The route manifest contains metadata about your routes (JavaScript/CSS imports, whether routes have `loaders`/`actions`, etc.) but not the actual route module implementations. This allows React Router to understand your application's structure without downloading unnecessary route information. + +## Route Discovery Process + +When a user navigates to a new route that isn't in the current manifest: + +1. **Route Discovery Request** - React Router makes a request to the internal `/__manifest` endpoint +2. **Manifest Patch** - The server responds with the required route information +3. **Route Loading** - React Router loads the necessary route modules and data +4. **Navigation** - The user navigates to the new route + +## Eager Discovery Optimization + +To prevent navigation waterfalls, React Router implements eager route discovery. All [``](../api/components/Link) and [``](../api/components/NavLink) components rendered on the current page are automatically discovered via a batched request to the server. + +This discovery request typically completes before users click any links, making subsequent navigation feel synchronous even with lazy route discovery enabled. + +```tsx +// Links are automatically discovered by default +Dashboard + +// Opt out of discovery for specific links +Admin +``` + +## Performance Benefits + +Lazy Route Discovery provides several performance improvements: + +- **Faster Initial Load** - Smaller initial bundle size by excluding unused route metadata +- **Reduced Memory Usage** - Route information is loaded only when needed +- **Scalability** - Applications with hundreds of routes see more significant benefits + +## Configuration + +You can configure route discovery behavior in your `react-router.config.ts`: + +```tsx filename=react-router.config.ts +export default { + // Default: lazy discovery with /__manifest endpoint + routeDiscovery: { + mode: "lazy", + manifestPath: "/__manifest", + }, + + // Custom manifest path (useful for multiple apps on same domain) + routeDiscovery: { + mode: "lazy", + manifestPath: "/my-app-manifest", + }, + + // Disable lazy discovery (include all routes initially) + routeDiscovery: { mode: "initial" }, +} satisfies Config; +``` + +## Deployment Considerations + +When using lazy route discovery, ensure your deployment setup handles manifest requests properly: + +- **Route Handling** - Ensure `/__manifest` requests reach your React Router handler +- **CDN Caching** - If using CDN/edge caching, include `version` and `p` query parameters in your cache key for the manifest endpoint +- **Multiple Applications** - Use a custom `manifestPath` if running multiple React Router applications on the same domain