feat(react-router): allow to preload route chunk (#3016)

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Manuel Schiller <manuel.schiller@caligano.de>

docs/framework/react/api/router/RouterType.md

@@ -177,6 +177,12 @@ Preloads all of the matches that match the provided `NavigateOptions`.
 - Returns
   - A promise that resolves with an array of all of the route matches that were preloaded.
 
+### `.loadRouteChunk` method
+
+Loads the JS chunk of the route.
+
+- Type: `(route: AnyRoute) => Promise<void>`
+
 ### `.matchRoute` method
 
 Matches a pathname and search params against the router's route tree and returns a route match's params or false if no match was found.

docs/framework/react/guide/preloading.md

@@ -120,3 +120,26 @@ function Component() {
   return <div />
 }
 ```
+
+If you need to preload only the JS chunk of a route, you can use the router's `loadRouteChunk` method. It accepts a route object and returns a promise that resolves when the route chunk is loaded.
+
+```tsx
+function Component() {
+  const router = useRouter()
+
+  useEffect(() => {
+    try {
+      const postsRoute = router.routesByPath['/posts']
+      await Promise.all([
+        router.loadRouteChunk(router.routesByPath['/']),
+        router.loadRouteChunk(postsRoute),
+        router.loadRouteChunk(postsRoute.parentRoute),
+      ])
+    } catch (err) {
+      // Failed to preload route chunk
+    }
+  }, [])
+
+  return <div />
+}
+```

packages/react-router/src/router.ts

@@ -2553,37 +2553,7 @@ export class Router<
 
                         // Actually run the loader and handle the result
                         try {
-                          if (route._lazyPromise === undefined) {
-                            if (route.lazyFn) {
-                              route._lazyPromise = route
-                                .lazyFn()
-                                .then((lazyRoute) => {
-                                  // explicitly don't copy over the lazy route's id
-                                  const { id: _id, ...options } =
-                                    lazyRoute.options
-                                  Object.assign(route.options, options)
-                                })
-                            } else {
-                              route._lazyPromise = Promise.resolve()
-                            }
-                          }
-
-                          // If for some reason lazy resolves more lazy components...
-                          // We'll wait for that before pre attempt to preload any
-                          // components themselves.
-                          if (route._componentsPromise === undefined) {
-                            route._componentsPromise = route._lazyPromise.then(
-                              () =>
-                                Promise.all(
-                                  componentTypes.map(async (type) => {
-                                    const component = route.options[type]
-                                    if ((component as any)?.preload) {
-                                      await (component as any).preload()
-                                    }
-                                  }),
-                                ),
-                            )
-                          }
+                          this.loadRouteChunk(route)
 
                           updateMatch(matchId, (prev) => ({
                             ...prev,
@@ -2821,6 +2791,37 @@ export class Router<
     this.clearCache({ filter })
   }
 
+  loadRouteChunk = (route: AnyRoute) => {
+    if (route._lazyPromise === undefined) {
+      if (route.lazyFn) {
+        route._lazyPromise = route.lazyFn().then((lazyRoute) => {
+          // explicitly don't copy over the lazy route's id
+          const { id: _id, ...options } = lazyRoute.options
+          Object.assign(route.options, options)
+        })
+      } else {
+        route._lazyPromise = Promise.resolve()
+      }
+    }
+
+    // If for some reason lazy resolves more lazy components...
+    // We'll wait for that before pre attempt to preload any
+    // components themselves.
+    if (route._componentsPromise === undefined) {
+      route._componentsPromise = route._lazyPromise.then(() =>
+        Promise.all(
+          componentTypes.map(async (type) => {
+            const component = route.options[type]
+            if ((component as any)?.preload) {
+              await (component as any).preload()
+            }
+          }),
+        ),
+      )
+    }
+    return route._componentsPromise
+  }
+
   preloadRoute = async <
     TFrom extends RoutePaths<TRouteTree> | string = string,
     TTo extends string | undefined = undefined,