use FetchStrategy to control prefetching behavior everywhere

Author: lubieowoce

packages/next/errors.json

@@ -755,5 +755,7 @@
   "754": "%s cannot be used outside of a request context.",
   "755": "Route must be a string",
   "756": "Route %s not found",
-  "757": "Unknown styled string type: %s"
+  "757": "Unknown styled string type: %s",
+  "758": "Unexpected FetchStrategy: %s",
+  "759": "Unexpected PrefetchKind: %s"
 }

packages/next/src/client/app-dir/form.tsx

@@ -7,7 +7,6 @@ import {
   AppRouterContext,
   type AppRouterInstance,
 } from '../../shared/lib/app-router-context.shared-runtime'
-import { PrefetchKind } from '../components/router-reducer/router-reducer-types'
 import {
   checkFormActionUrl,
   createFormSubmitDestinationUrl,
@@ -20,6 +19,7 @@ import {
   mountFormInstance,
   unmountPrefetchableInstance,
 } from '../components/links'
+import { FetchStrategy } from '../components/segment-cache'
 
 export type { FormProps }
 
@@ -99,7 +99,13 @@ export default function Form({
   const observeFormVisibilityOnMount = useCallback(
     (element: HTMLFormElement) => {
       if (isPrefetchEnabled && router !== null) {
-        mountFormInstance(element, actionProp, router, PrefetchKind.AUTO)
+        mountFormInstance(
+          element,
+          actionProp,
+          router,
+          // We default to PPR. We'll discover whether or not the route supports it with the initial prefetch.
+          FetchStrategy.PPR
+        )
       }
       return () => {
         unmountPrefetchableInstance(element)

packages/next/src/client/app-dir/link.tsx

@@ -4,7 +4,6 @@ import React, { createContext, useContext, useOptimistic, useRef } from 'react'
 import type { UrlObject } from 'url'
 import { formatUrl } from '../../shared/lib/router/utils/format-url'
 import { AppRouterContext } from '../../shared/lib/app-router-context.shared-runtime'
-import { PrefetchKind } from '../components/router-reducer/router-reducer-types'
 import { useMergedRef } from '../use-merged-ref'
 import { isAbsoluteUrl } from '../../shared/lib/utils'
 import { addBasePath } from '../add-base-path'
@@ -21,6 +20,7 @@ import {
 import { isLocalURL } from '../../shared/lib/router/utils/is-local-url'
 import { dispatchNavigateAction } from '../components/app-router-instance'
 import { errorOnce } from '../../shared/lib/utils/error-once'
+import { FetchStrategy } from '../components/segment-cache'
 
 type Url = string | UrlObject
 type RequiredKeys<T> = {
@@ -363,10 +363,11 @@ export default function LinkComponent(
    * - false: we will not prefetch if in the viewport at all
    * - 'unstable_dynamicOnHover': this starts in "auto" mode, but switches to "full" when the link is hovered
    */
-  const appPrefetchKind =
+  const fetchStrategy =
     prefetchProp === null || prefetchProp === 'auto'
-      ? PrefetchKind.AUTO
-      : PrefetchKind.FULL
+      ? // We default to PPR. We'll discover whether or not the route supports it with the initial prefetch.
+        FetchStrategy.PPR
+      : FetchStrategy.Full
 
   if (process.env.NODE_ENV !== 'production') {
     function createPropError(args: {
@@ -581,7 +582,7 @@ export default function LinkComponent(
           element,
           href,
           router,
-          appPrefetchKind,
+          fetchStrategy,
           prefetchEnabled,
           setOptimisticLinkStatus
         )
@@ -595,7 +596,7 @@ export default function LinkComponent(
         unmountPrefetchableInstance(element)
       }
     },
-    [prefetchEnabled, href, router, appPrefetchKind, setOptimisticLinkStatus]
+    [prefetchEnabled, href, router, fetchStrategy, setOptimisticLinkStatus]
   )
 
   const mergedRef = useMergedRef(observeLinkVisibilityOnMount, childRef)

packages/next/src/client/components/app-router-instance.ts

@@ -14,7 +14,10 @@ import {
 import { reducer } from './router-reducer/router-reducer'
 import { startTransition } from 'react'
 import { isThenable } from '../../shared/lib/is-thenable'
-import { prefetch as prefetchWithSegmentCache } from './segment-cache'
+import {
+  convertPrefetchKindToFetchStrategy,
+  prefetch as prefetchWithSegmentCache,
+} from './segment-cache'
 import { dispatchAppRouterAction } from './use-action-queue'
 import { addBasePath } from '../add-base-path'
 import { createPrefetchURL, isExternalURL } from './app-router'
@@ -323,11 +326,16 @@ export const publicAppRouterInstance: AppRouterInstance = {
       // cache. So we don't need to dispatch an action.
       (href: string, options?: PrefetchOptions) => {
         const actionQueue = getAppRouterActionQueue()
+        const prefetchKind = options?.kind ?? PrefetchKind.AUTO
+        if (prefetchKind === PrefetchKind.TEMPORARY) {
+          // This concept doesn't exist in the segment cache implementation.
+          return
+        }
         prefetchWithSegmentCache(
           href,
           actionQueue.state.nextUrl,
           actionQueue.state.tree,
-          options?.kind === PrefetchKind.FULL,
+          convertPrefetchKindToFetchStrategy(prefetchKind),
           options?.onInvalidate ?? null
         )
       }

packages/next/src/client/components/links.ts

@@ -2,8 +2,11 @@ import type { FlightRouterState } from '../../server/app-render/types'
 import type { AppRouterInstance } from '../../shared/lib/app-router-context.shared-runtime'
 import { getCurrentAppRouterState } from './app-router-instance'
 import { createPrefetchURL } from './app-router'
-import { PrefetchKind } from './router-reducer/router-reducer-types'
-import { isPrefetchTaskDirty } from './segment-cache'
+import {
+  convertFetchStrategyToPrefetchKind,
+  FetchStrategy,
+  isPrefetchTaskDirty,
+} from './segment-cache'
 import { createCacheKey } from './segment-cache'
 import {
   type PrefetchTask,
@@ -22,7 +25,7 @@ type Element = LinkElement | HTMLFormElement
 // shape for both to prevent a polymorphic de-opt in the VM.
 type LinkOrFormInstanceShared = {
   router: AppRouterInstance
-  kind: PrefetchKind.AUTO | PrefetchKind.FULL
+  fetchStrategy: FetchStrategy
 
   isVisible: boolean
 
@@ -140,7 +143,7 @@ export function mountLinkInstance(
   element: LinkElement,
   href: string,
   router: AppRouterInstance,
-  kind: PrefetchKind.AUTO | PrefetchKind.FULL,
+  fetchStrategy: FetchStrategy,
   prefetchEnabled: boolean,
   setOptimisticLinkStatus: (status: { pending: boolean }) => void
 ): LinkInstance {
@@ -149,7 +152,7 @@ export function mountLinkInstance(
     if (prefetchURL !== null) {
       const instance: PrefetchableLinkInstance = {
         router,
-        kind,
+        fetchStrategy,
         isVisible: false,
         prefetchTask: null,
         prefetchHref: prefetchURL.href,
@@ -165,7 +168,7 @@ export function mountLinkInstance(
   // track its optimistic state (i.e. useLinkStatus).
   const instance: NonPrefetchableLinkInstance = {
     router,
-    kind,
+    fetchStrategy,
     isVisible: false,
     prefetchTask: null,
     prefetchHref: null,
@@ -178,7 +181,7 @@ export function mountFormInstance(
   element: HTMLFormElement,
   href: string,
   router: AppRouterInstance,
-  kind: PrefetchKind.AUTO | PrefetchKind.FULL
+  fetchStrategy: FetchStrategy
 ): void {
   const prefetchURL = coercePrefetchableUrl(href)
   if (prefetchURL === null) {
@@ -190,7 +193,7 @@ export function mountFormInstance(
   }
   const instance: FormInstance = {
     router,
-    kind,
+    fetchStrategy,
     isVisible: false,
     prefetchTask: null,
     prefetchHref: prefetchURL.href,
@@ -261,7 +264,7 @@ export function onNavigationIntent(
       unstable_upgradeToDynamicPrefetch
     ) {
       // Switch to a full, dynamic prefetch
-      instance.kind = PrefetchKind.FULL
+      instance.fetchStrategy = FetchStrategy.Full
     }
     rescheduleLinkPrefetch(instance, PrefetchPriority.Intent)
   }
@@ -303,7 +306,7 @@ function rescheduleLinkPrefetch(
       instance.prefetchTask = scheduleSegmentPrefetchTask(
         cacheKey,
         treeAtTimeOfPrefetch,
-        instance.kind === PrefetchKind.FULL,
+        instance.fetchStrategy,
         priority,
         null
       )
@@ -313,7 +316,7 @@ function rescheduleLinkPrefetch(
       reschedulePrefetchTask(
         existingPrefetchTask,
         treeAtTimeOfPrefetch,
-        instance.kind === PrefetchKind.FULL,
+        instance.fetchStrategy,
         priority
       )
     }
@@ -347,7 +350,7 @@ export function pingVisibleLinks(
     instance.prefetchTask = scheduleSegmentPrefetchTask(
       cacheKey,
       tree,
-      instance.kind === PrefetchKind.FULL,
+      instance.fetchStrategy,
       PrefetchPriority.Default,
       null
     )
@@ -364,7 +367,7 @@ function prefetchWithOldCacheImplementation(instance: PrefetchableInstance) {
     // note that `appRouter.prefetch()` is currently sync,
     // so we have to wrap this call in an async function to be able to catch() errors below.
     return instance.router.prefetch(instance.prefetchHref, {
-      kind: instance.kind,
+      kind: convertFetchStrategyToPrefetchKind(instance.fetchStrategy),
     })
   }
 

packages/next/src/client/components/segment-cache-impl/cache.ts

@@ -63,6 +63,7 @@ import {
   DOC_PREFETCH_RANGE_HEADER_VALUE,
   doesExportedHtmlMatchBuildId,
 } from '../../../shared/lib/segment-cache/output-export-prefetch-encoding'
+import { FetchStrategy } from '../segment-cache'
 
 // A note on async/await when working in the prefetch cache:
 //
@@ -165,12 +166,6 @@ export type RouteCacheEntry =
   | FulfilledRouteCacheEntry
   | RejectedRouteCacheEntry
 
-export const enum FetchStrategy {
-  PPR,
-  Full,
-  LoadingBoundary,
-}
-
 type SegmentCacheEntryShared = {
   staleAt: number
   fetchStrategy: FetchStrategy
@@ -415,7 +410,8 @@ export function getSegmentKeypathForTask(
   // If we're fetching using PPR, we do not need to include the search params in
   // the cache key, because the search params are treated as dynamic data. The
   // cache entry is valid for all possible search param values.
-  const isDynamicTask = task.includeDynamicData || !route.isPPREnabled
+  const isDynamicTask =
+    task.fetchStrategy === FetchStrategy.Full || !route.isPPREnabled
   return isDynamicTask && path.endsWith('/' + PAGE_SEGMENT_KEY)
     ? [path, route.renderedSearch]
     : [path]
@@ -1161,8 +1157,15 @@ export async function fetchRouteOnCacheMiss(
         routeIsPPREnabled
       )
     } else {
-      // PPR is not enabled for this route. The server responds with a
-      // different format (FlightRouterState) that we need to convert.
+      // PPR is not enabled for this route.
+
+      // We start "auto" prefetches with a PPR strategy by default. If it's that (and not e.g. a `FetchStrategy.Full`),
+      // we should update the task accordingly.
+      if (task.fetchStrategy === FetchStrategy.PPR) {
+        task.fetchStrategy = FetchStrategy.LoadingBoundary
+      }
+
+      // For non-PPR routes, the server responds with a different format (FlightRouterState) that we need to convert.
       // TODO: We will unify the responses eventually. I'm keeping the types
       // separate for now because FlightRouterState has so many
       // overloaded concerns.

packages/next/src/client/components/segment-cache-impl/fetch-strategy.ts

@@ -0,0 +1,45 @@
+import { InvariantError } from '../../../shared/lib/invariant-error'
+import { PrefetchKind } from '../router-reducer/router-reducer-types'
+
+export const enum FetchStrategy {
+  PPR,
+  Full,
+  LoadingBoundary,
+}
+
+export function convertFetchStrategyToPrefetchKind(
+  fetchStrategy: FetchStrategy
+): PrefetchKind.AUTO | PrefetchKind.FULL {
+  switch (fetchStrategy) {
+    case FetchStrategy.LoadingBoundary:
+    case FetchStrategy.PPR: {
+      return PrefetchKind.AUTO
+    }
+    case FetchStrategy.Full: {
+      return PrefetchKind.FULL
+    }
+    default: {
+      fetchStrategy satisfies never
+      throw new InvariantError(`Unexpected FetchStrategy: ${fetchStrategy}`)
+    }
+  }
+}
+
+export function convertPrefetchKindToFetchStrategy(
+  prefetchKind: PrefetchKind.AUTO | PrefetchKind.FULL
+) {
+  switch (prefetchKind) {
+    case PrefetchKind.AUTO: {
+      // We default to PPR. We'll discover whether or not the route supports it with the initial prefetch.
+      return FetchStrategy.PPR
+    }
+    case PrefetchKind.FULL: {
+      return FetchStrategy.Full
+    }
+
+    default: {
+      prefetchKind satisfies never
+      throw new InvariantError(`Unexpected PrefetchKind: ${prefetchKind}`)
+    }
+  }
+}

packages/next/src/client/components/segment-cache-impl/prefetch.ts

@@ -2,7 +2,7 @@ import type { FlightRouterState } from '../../../server/app-render/types'
 import { createPrefetchURL } from '../app-router'
 import { createCacheKey } from './cache-key'
 import { schedulePrefetchTask } from './scheduler'
-import { PrefetchPriority } from '../segment-cache'
+import { type FetchStrategy, PrefetchPriority } from '../segment-cache'
 
 /**
  * Entrypoint for prefetching a URL into the Segment Cache.
@@ -12,8 +12,8 @@ import { PrefetchPriority } from '../segment-cache'
  * Roughly corresponds to the current URL.
  * @param treeAtTimeOfPrefetch - The FlightRouterState at the time the prefetch
  * was requested. This is only used when PPR is disabled.
- * @param includeDynamicData - Whether to prefetch dynamic data, in addition to
- * static data. This is used by <Link prefetch={true}>.
+ * @param fetchStrategy - Whether to prefetch dynamic data, in addition to
+ * static data. This is used by `<Link prefetch={true}>`.
  * @param onInvalidate - A callback that will be called when the prefetch cache
  * When called, it signals to the listener that the data associated with the
  * prefetch may have been invalidated from the cache. This is not a live
@@ -28,7 +28,7 @@ export function prefetch(
   href: string,
   nextUrl: string | null,
   treeAtTimeOfPrefetch: FlightRouterState,
-  includeDynamicData: boolean,
+  fetchStrategy: FetchStrategy,
   onInvalidate: null | (() => void)
 ) {
   const url = createPrefetchURL(href)
@@ -40,7 +40,7 @@ export function prefetch(
   schedulePrefetchTask(
     cacheKey,
     treeAtTimeOfPrefetch,
-    includeDynamicData,
+    fetchStrategy,
     PrefetchPriority.Default,
     onInvalidate
   )