feat(react-router): add preload='render' support (#2644)

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

@@ -33,7 +33,7 @@ The `LinkOptions` object accepts/contains the following properties:
 
 ### `preload`
 
-- Type: `false | 'intent' | 'viewport'`
+- Type: `false | 'intent' | 'viewport' | 'render'`
 - Optional
 - If set, the link's preloading strategy will be set to this value.
 - See the [Preloading guide](../../guide/preloading.md) for more information.

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

@@ -46,12 +46,13 @@ The `RouterOptions` type accepts an object with the following properties and met
 
 ### `defaultPreload` property
 
-- Type: `undefined | false | 'intent' | 'viewport'`
+- Type: `undefined | false | 'intent' | 'viewport' | 'render'`
 - Optional
 - Defaults to `false`
 - If `false`, routes will not be preloaded by default in any way.
 - If `'intent'`, routes will be preloaded by default when the user hovers over a link or a `touchstart` event is detected on a `<Link>`.
 - If `'viewport'`, routes will be preloaded by default when they are within the viewport of the browser.
+- If `'render'`, routes will be preloaded by default as soon as they are rendered in the DOM.
 
 ### `defaultPreloadDelay` property
 

docs/framework/react/guide/preloading.md

@@ -13,7 +13,8 @@ Preloading in TanStack Router is a way to load a route before the user actually
   - Preloading by **"viewport**" works by using the Intersection Observer API to preload the dependencies for the destination route when the `<Link>` component is in the viewport.
   - This strategy is useful for preloading routes that are below the fold or off-screen.
 - Render
-  - **Coming soon!**
+  - Preloading by **"render"** works by preloading the dependencies for the destination route as soon as the `<Link>` component is rendered in the DOM.
+  - This strategy is useful for preloading routes that are always needed.
 
 ## How long does preloaded data stay in memory?
 

packages/react-router/src/link.tsx

@@ -9,6 +9,7 @@ import {
   functionalUpdate,
   useForwardedRef,
   useIntersectionObserver,
+  useLayoutEffect,
 } from './utils'
 import { exactPathTest, removeTrailingSlash } from './path'
 import type { ParsedLocation } from './location'
@@ -497,7 +498,7 @@ export interface LinkOptionsProps {
    * - `'intent'` - Preload the linked route on hover and cache it for this many milliseconds in hopes that the user will eventually navigate there.
    * - `'viewport'` - Preload the linked route when it enters the viewport
    */
-  preload?: false | 'intent' | 'viewport'
+  preload?: false | 'intent' | 'viewport' | 'render'
   /**
    * When a preload strategy is set, this delays the preload by this many milliseconds.
    * If the user exits the link before this delay, the preload will be cancelled.
@@ -589,6 +590,7 @@ export function useLinkProps<
 ): React.ComponentPropsWithRef<'a'> {
   const router = useRouter()
   const [isTransitioning, setIsTransitioning] = React.useState(false)
+  const hasRenderFetched = React.useRef(false)
   const innerRef = useForwardedRef(forwardedRef)
 
   const {
@@ -722,9 +724,19 @@ export function useLinkProps<
     innerRef,
     preloadViewportIoCallback,
     { rootMargin: '100px' },
-    { disabled: !!disabled || preload !== 'viewport' },
+    { disabled: !!disabled || !(preload === 'viewport') },
   )
 
+  useLayoutEffect(() => {
+    if (hasRenderFetched.current) {
+      return
+    }
+    if (!disabled && preload === 'render') {
+      doPreload()
+      hasRenderFetched.current = true
+    }
+  }, [disabled, doPreload, preload])
+
   if (type === 'external') {
     return {
       ...propsSafeToSpread,

packages/react-router/src/router.ts

@@ -211,7 +211,7 @@ export interface RouterOptions<
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpreload-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading)
    */
-  defaultPreload?: false | 'intent' | 'viewport'
+  defaultPreload?: false | 'intent' | 'viewport' | 'render'
   /**
    * The delay in milliseconds that a route must be hovered over or touched before it is preloaded.
    *
@@ -1622,7 +1622,7 @@ export class Router<
         })
 
         if (foundMask) {
-          const { from, ...maskProps } = foundMask
+          const { from: _from, ...maskProps } = foundMask
           maskedDest = {
             ...pick(opts, ['from']),
             ...maskProps,

packages/react-router/tests/link.test.tsx

@@ -3613,7 +3613,7 @@ describe('Link', () => {
     expect(stringifyParamsMock).toHaveBeenCalledWith({ postId: 0 })
   })
 
-  test.each([false, 'intent'] as const)(
+  test.each([false, 'intent', 'render'] as const)(
     'Router.preload="%s", should not trigger the IntersectionObserver\'s observe and disconnect methods',
     async (preload) => {
       const rootRoute = createRootRoute()
@@ -3643,6 +3643,37 @@ describe('Link', () => {
     },
   )
 
+  test.each([false, 'intent', 'viewport', 'render'] as const)(
+    'Router.preload="%s" with Link.preload="false", should not trigger the IntersectionObserver\'s observe method',
+    async (preload) => {
+      const rootRoute = createRootRoute()
+      const indexRoute = createRoute({
+        getParentRoute: () => rootRoute,
+        path: '/',
+        component: () => (
+          <>
+            <h1>Index Heading</h1>
+            <Link to="/" preload={false}>
+              Index Link
+            </Link>
+          </>
+        ),
+      })
+
+      const router = createRouter({
+        routeTree: rootRoute.addChildren([indexRoute]),
+        defaultPreload: preload,
+      })
+
+      render(<RouterProvider router={router} />)
+
+      const indexLink = await screen.findByRole('link', { name: 'Index Link' })
+      expect(indexLink).toBeInTheDocument()
+
+      expect(ioObserveMock).not.toBeCalled()
+    },
+  )
+
   test('Router.preload="viewport", should trigger the IntersectionObserver\'s observe and disconnect methods', async () => {
     const rootRoute = createRootRoute()
     const indexRoute = createRoute({
@@ -3673,32 +3704,44 @@ describe('Link', () => {
     expect(ioDisconnectMock).toBeCalledTimes(1) // since React.StrictMode is enabled it should have disconnected
   })
 
-  test('Router.preload="viewport" with Link.preload="false", should not trigger the IntersectionObserver\'s observe method', async () => {
+  test("Router.preload='render', should trigger the route loader on render", async () => {
+    const mock = vi.fn()
+
     const rootRoute = createRootRoute()
     const indexRoute = createRoute({
       getParentRoute: () => rootRoute,
       path: '/',
+      loader: () => {
+        mock()
+      },
       component: () => (
         <>
           <h1>Index Heading</h1>
-          <Link to="/" preload={false}>
-            Index Link
-          </Link>
+          <Link to="/about">About Link</Link>
+        </>
+      ),
+    })
+    const aboutRoute = createRoute({
+      getParentRoute: () => rootRoute,
+      path: '/about',
+      component: () => (
+        <>
+          <h1>About Heading</h1>
         </>
       ),
     })
 
     const router = createRouter({
-      routeTree: rootRoute.addChildren([indexRoute]),
-      defaultPreload: 'viewport',
+      routeTree: rootRoute.addChildren([aboutRoute, indexRoute]),
+      defaultPreload: 'render',
     })
 
     render(<RouterProvider router={router} />)
 
-    const indexLink = await screen.findByRole('link', { name: 'Index Link' })
-    expect(indexLink).toBeInTheDocument()
+    const aboutLink = await screen.findByRole('link', { name: 'About Link' })
+    expect(aboutLink).toBeInTheDocument()
 
-    expect(ioObserveMock).not.toBeCalled()
+    expect(mock).toHaveBeenCalledTimes(1)
   })
 
   test('Router.preload="intent", pendingComponent renders during unresolved route loader', async () => {