UNPKG

3.59 kB Markdown View Raw
1---
2title: Lazy Route Discovery
3---
4
5# Lazy Route Discovery
6
7[MODES: framework]
8
9Lazy 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.
10
11With 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.
12
13The 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.
14
15## Route Discovery Process
16
17When a user navigates to a new route that isn't in the current manifest:
18
191. **Route Discovery Request** - React Router makes a request to the internal `/__manifest` endpoint
202. **Manifest Patch** - The server responds with the required route information
213. **Route Loading** - React Router loads the necessary route modules and data
224. **Navigation** - The user navigates to the new route
23
24## Eager Discovery Optimization
25
26To prevent navigation waterfalls, React Router implements eager route discovery. All [`<Link>`](../api/components/Link) and [`<NavLink>`](../api/components/NavLink) components rendered on the current page are automatically discovered via a batched request to the server.
27
28This discovery request typically completes before users click any links, making subsequent navigation feel synchronous even with lazy route discovery enabled.
29
30```tsx
31// Links are automatically discovered by default
32<Link to="/dashboard">Dashboard</Link>
33
34// Opt out of discovery for specific links
35<Link to="/admin" discover="none">Admin</Link>
36```
37
38## Performance Benefits
39
40Lazy Route Discovery provides several performance improvements:
41
42- **Faster Initial Load** - Smaller initial bundle size by excluding unused route metadata
43- **Reduced Memory Usage** - Route information is loaded only when needed
44- **Scalability** - Applications with hundreds of routes see more significant benefits
45
46## Configuration
47
48You can configure route discovery behavior in your `react-router.config.ts`:
49
50```tsx filename=react-router.config.ts
51export default {
52 // Default: lazy discovery with /__manifest endpoint
53 routeDiscovery: {
54 mode: "lazy",
55 manifestPath: "/__manifest",
56 },
57
58 // Custom manifest path (useful for multiple apps on same domain)
59 routeDiscovery: {
60 mode: "lazy",
61 manifestPath: "/my-app-manifest",
62 },
63
64 // Disable lazy discovery (include all routes initially)
65 routeDiscovery: { mode: "initial" },
66} satisfies Config;
67```
68
69## Deployment Considerations
70
71When using lazy route discovery, ensure your deployment setup handles manifest requests properly:
72
73- **Route Handling** - Ensure `/__manifest` requests reach your React Router handler
74- **CDN Caching** - If using CDN/edge caching, include `version` and `paths` query parameters in your cache key for the manifest endpoint
75- **Multiple Applications** - Use a custom `manifestPath` if running multiple React Router applications on the same domain
76
77## Application-Controlled Discovery
78
79Use the experimental `unstable_useRouteDiscovery` hook to discover selected destinations, complete the route tree after startup, or control manifest-mismatch recovery. See [Application-Controlled Route Discovery](../how-to/route-discovery).
80
\No newline at end of file