Add onInvalidate option to router.prefetch

This commit adds an `onInvalidate` callback to `router.prefetch()` so
custom `<Link>` implementations can re-prefetch data when it
becomes stale.

The callback is invoked when the data associated with the prefetch may
have been invalidated (e.g. by `revalidatePath` or `revalidateTag`).

This is not a live subscription and should not be treated as one. It's a
one-time callback per prefetch request that acts as a signal: "If you
care about the freshness of this data, now would be a good time
to re-prefetch."

The supported use case is for advanced clients who opt out of rendering
the built-in `<Link>` component (e.g. to customize visibility tracking
or polling behavior) but still want to retain proper cache integration.
When the callback is fired, the component can trigger a new call to
`router.prefetch()` with the same parameters, including a new
`onInvalidate` callback to continue the cycle.

(For reference, `<Link>` handles this automatically. This API exists to
give custom implementations access to the same underlying behavior.)

Note that the callback *may* be invoked even if the prefetched data is
still cached. This is intentional—prefetching in the app router is a
pull-based mechanism, not a push-based one. Rather than subscribing to
the lifecycle of specific cache entries, the app occasionally polls the
prefetch layer to check for missing or stale data.

Calling `router.prefetch()` does not necessarily result in a network
request. If the data is already cached, the call is a no-op. This makes
polling a practical way to check cache freshness over time without
incurring unnecessary requests.

Author: acdlite

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

@@ -321,7 +321,8 @@ export const publicAppRouterInstance: AppRouterInstance = {
           href,
           actionQueue.state.nextUrl,
           actionQueue.state.tree,
-          options?.kind === PrefetchKind.FULL
+          options?.kind === PrefetchKind.FULL,
+          options?.onInvalidate ?? null
         )
       }
     : (href: string, options?: PrefetchOptions) => {

Diff for: packages/next/src/client/components/links.ts

@@ -322,7 +322,8 @@ function rescheduleLinkPrefetch(instance: PrefetchableInstance) {
         cacheKey,
         treeAtTimeOfPrefetch,
         instance.kind === PrefetchKind.FULL,
-        priority
+        priority,
+        null
       )
     } else {
       // We already have an old task object that we can reschedule. This is
@@ -378,7 +379,8 @@ export function pingVisibleLinks(
       cacheKey,
       tree,
       instance.kind === PrefetchKind.FULL,
-      priority
+      priority,
+      null
     )
     instance.cacheVersion = getCurrentCacheVersion()
   }

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

@@ -245,6 +245,14 @@ let segmentCacheLru = createLRU<SegmentCacheEntry>(
   onSegmentLRUEviction
 )
 
+// All invalidation listeners for the whole cache are tracked in single set.
+// Since we don't yet support tag or path-based invalidation, there's no point
+// tracking them any more granularly than this. Once we add granular
+// invalidation, that may change, though generally the model is to just notify
+// the listeners and allow the caller to poll the prefetch cache with a new
+// prefetch task if desired.
+let invalidationListeners: Set<PrefetchTask> | null = null
+
 // Incrementing counter used to track cache invalidations.
 let currentCacheVersion = 0
 
@@ -276,6 +284,52 @@ export function revalidateEntireCache(
 
   // Prefetch all the currently visible links again, to re-fill the cache.
   pingVisibleLinks(nextUrl, tree)
+
+  // Similarly, notify all invalidation listeners (i.e. those passed to
+  // `router.prefetch(onInvalidate)`), so they can trigger a new prefetch
+  // if needed.
+  if (invalidationListeners !== null) {
+    const tasks = invalidationListeners
+    invalidationListeners = null
+    for (const task of tasks) {
+      notifyInvalidationListener(task)
+    }
+  }
+}
+
+function attachInvalidationListener(task: PrefetchTask): void {
+  // This function is called whenever a prefetch task reads a cache entry. If
+  // the task has an onInvalidate function associated with it — i.e. the one
+  // optionally passed to router.prefetch(onInvalidate) — then we attach that
+  // listener to the every cache entry that the task reads. Then, if an entry
+  // is invalidated, we call the function.
+  if (task.onInvalidate !== null) {
+    if (invalidationListeners === null) {
+      invalidationListeners = new Set([task])
+    } else {
+      invalidationListeners.add(task)
+    }
+  }
+}
+
+function notifyInvalidationListener(task: PrefetchTask): void {
+  const onInvalidate = task.onInvalidate
+  if (onInvalidate !== null) {
+    // Clear the callback from the task object to guarantee it's not called more
+    // than once.
+    task.onInvalidate = null
+
+    // This is a user-space function, so we must wrap in try/catch.
+    try {
+      onInvalidate()
+    } catch (error) {
+      if (typeof reportError === 'function') {
+        reportError(error)
+      } else {
+        console.error(error)
+      }
+    }
+  }
 }
 
 export function readExactRouteCacheEntry(
@@ -445,6 +499,8 @@ export function readOrCreateRouteCacheEntry(
   now: number,
   task: PrefetchTask
 ): RouteCacheEntry {
+  attachInvalidationListener(task)
+
   const key = task.key
   const existingEntry = readRouteCacheEntry(now, key)
   if (existingEntry !== null) {

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

@@ -9,17 +9,27 @@ import { PrefetchPriority } from '../segment-cache'
  * @param href - The URL to prefetch. Typically this will come from a <Link>,
  * or router.prefetch. It must be validated before we attempt to prefetch it.
  * @param nextUrl - A special header used by the server for interception routes.
- * Roughly  corresponds to the current URL.
+ * 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 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
+ * subscription — it's called at most once per `prefetch` call. The only
+ * supported use case is to trigger a new prefetch inside the listener, if
+ * desired. It also may be called even in cases where the associated data is
+ * still cached. Prefetching is a poll-based (pull) operation, not an event-
+ * based (push) one. Rather than subscribe to specific cache entries, you
+ * occasionally poll the prefetch cache to check if anything is missing.
  */
 export function prefetch(
   href: string,
   nextUrl: string | null,
   treeAtTimeOfPrefetch: FlightRouterState,
-  includeDynamicData: boolean
+  includeDynamicData: boolean,
+  onInvalidate: null | (() => void)
 ) {
   const url = createPrefetchURL(href)
   if (url === null) {
@@ -31,6 +41,7 @@ export function prefetch(
     cacheKey,
     treeAtTimeOfPrefetch,
     includeDynamicData,
-    PrefetchPriority.Default
+    PrefetchPriority.Default,
+    onInvalidate
   )
 }

Diff for: packages/next/src/client/components/segment-cache-impl/scheduler.ts

@@ -105,6 +105,11 @@ export type PrefetchTask = {
    */
   isCanceled: boolean
 
+  /**
+   * The callback passed to `router.prefetch`, if given.
+   */
+  onInvalidate: null | (() => void)
+
   /**
    * The index of the task in the heap's backing array. Used to efficiently
    * change the priority of a task by re-sifting it, which requires knowing
@@ -182,7 +187,8 @@ export function schedulePrefetchTask(
   key: RouteCacheKey,
   treeAtTimeOfPrefetch: FlightRouterState,
   includeDynamicData: boolean,
-  priority: PrefetchPriority
+  priority: PrefetchPriority,
+  onInvalidate: null | (() => void)
 ): PrefetchTask {
   // Spawn a new prefetch task
   const task: PrefetchTask = {
@@ -194,6 +200,7 @@ export function schedulePrefetchTask(
     includeDynamicData,
     sortId: sortIdCounter++,
     isCanceled: false,
+    onInvalidate,
     _heapIndex: -1,
   }
   heapPush(taskHeap, task)

Diff for: packages/next/src/shared/lib/app-router-context.shared-runtime.ts

@@ -122,6 +122,7 @@ export interface NavigateOptions {
 
 export interface PrefetchOptions {
   kind: PrefetchKind
+  onInvalidate?: () => void
 }
 
 export interface AppRouterInstance {

Diff for: test/e2e/app-dir/segment-cache/revalidation/app/page.tsx

@@ -1,5 +1,9 @@
 import { revalidatePath, revalidateTag } from 'next/cache'
-import { LinkAccordion, FormAccordion } from '../components/link-accordion'
+import {
+  LinkAccordion,
+  FormAccordion,
+  ManualPrefetchLinkAccordion,
+} from '../components/link-accordion'
 import Link from 'next/link'
 
 export default async function Page() {
@@ -36,6 +40,12 @@ export default async function Page() {
             Form pointing to target page with prefetching enabled
           </FormAccordion>
         </li>
+        <li>
+          <ManualPrefetchLinkAccordion href="/greeting">
+            Manual link (router.prefetch) to target page with prefetching
+            enabled
+          </ManualPrefetchLinkAccordion>
+        </li>
         <li>
           <Link prefetch={false} href="/greeting">
             Link to target with prefetching disabled

Diff for: test/e2e/app-dir/segment-cache/revalidation/components/link-accordion.tsx

@@ -2,7 +2,8 @@
 
 import Link from 'next/link'
 import Form from 'next/form'
-import { useState } from 'react'
+import { useEffect, useState } from 'react'
+import { useRouter } from 'next/navigation'
 
 export function LinkAccordion({
   href,
@@ -61,3 +62,64 @@ export function FormAccordion({
     </>
   )
 }
+
+export function ManualPrefetchLinkAccordion({
+  href,
+  children,
+  prefetch,
+}: {
+  href: string
+  children: React.ReactNode
+  prefetch?: boolean
+}) {
+  const [isVisible, setIsVisible] = useState(false)
+  return (
+    <>
+      <input
+        type="checkbox"
+        checked={isVisible}
+        onChange={() => setIsVisible(!isVisible)}
+        data-manual-prefetch-link-accordion={href}
+      />
+      {isVisible ? (
+        <ManualPrefetchLink href={href} prefetch={prefetch}>
+          {children}
+        </ManualPrefetchLink>
+      ) : (
+        <>{children} (form is hidden)</>
+      )}
+    </>
+  )
+}
+
+function ManualPrefetchLink({
+  href,
+  children,
+  prefetch,
+}: {
+  href: string
+  children: React.ReactNode
+  prefetch?: boolean
+}) {
+  const router = useRouter()
+  useEffect(() => {
+    if (prefetch !== false) {
+      // For as long as the link is mounted, poll the prefetch cache whenever
+      // it's invalidated to ensure the data is fresh.
+      let didUnmount = false
+      const pollPrefetch = () => {
+        if (!didUnmount) {
+          // @ts-expect-error: onInvalidate is not yet part of public types
+          router.prefetch(href, {
+            onInvalidate: pollPrefetch,
+          })
+        }
+      }
+      pollPrefetch()
+      return () => {
+        didUnmount = true
+      }
+    }
+  }, [href, prefetch, router])
+  return <a href={href}>{children}</a>
+}

Diff for: test/e2e/app-dir/segment-cache/revalidation/segment-cache-revalidation.test.ts

@@ -150,6 +150,57 @@ describe('segment cache (revalidation)', () => {
     }, 'no-requests')
   })
 
+  it('call router.prefetch(..., {onInvalidate}) after cache is revalidated', async () => {
+    // This is the similar to the previous tests, but uses a custom Link
+    // implementation that calls router.prefetch manually. It demonstrates it's
+    // possible to simulate the revalidating behavior of Link using the manual
+    // prefetch API.
+    let act: ReturnType<typeof createRouterAct>
+    const browser = await next.browser('/', {
+      beforePageLoad(page: Playwright.Page) {
+        act = createRouterAct(page)
+      },
+    })
+
+    const linkVisibilityToggle = await browser.elementByCss(
+      'input[data-manual-prefetch-link-accordion="/greeting"]'
+    )
+
+    // Reveal the link that points to the target page to trigger a prefetch
+    await act(
+      async () => {
+        await linkVisibilityToggle.click()
+      },
+      {
+        includes: 'random-greeting',
+      }
+    )
+
+    // Perform an action that calls revalidatePath. This should cause the
+    // corresponding entry to be evicted from the client cache, and a new
+    // prefetch to be requested.
+    await act(
+      async () => {
+        const revalidateByPath = await browser.elementById('revalidate-by-path')
+        await revalidateByPath.click()
+      },
+      {
+        includes: 'random-greeting [1]',
+      }
+    )
+    TestLog.assert(['REQUEST: random-greeting'])
+
+    // Navigate to the target page.
+    await act(async () => {
+      const link = await browser.elementByCss('a[href="/greeting"]')
+      await link.click()
+      // Navigation should finish immedately because the page is
+      // fully prefetched.
+      const greeting = await browser.elementById('greeting')
+      expect(await greeting.innerHTML()).toBe('random-greeting [1]')
+    }, 'no-requests')
+  })
+
   it('evict client cache when Server Action calls revalidateTag', async () => {
     let act: ReturnType<typeof createRouterAct>
     const browser = await next.browser('/', {