Skip to content

Router prefetch does not fully warm route navigations #2099

Description

@jxom

Summary

[email protected] can leave prefetched router navigations cold. In the repro, routes are static and links use unstable_prefetchOnView, but clicking a visible, already-prefetched route still triggers route-specific loading work.

There seem to be two related issues:

  1. Production router prefetch code can preload the wrong client chunks.
  2. RSC prefetch stores the response, but does not reuse decoded elements on navigation, so client module references can still be resolved at click time.

Reproduction

Minimal repro: https://github.com/jxom/waku-prefetch-repro

pnpm install
pnpm build
pnpm start

Then:

  1. Open the local URL in a browser.
  2. Open DevTools Network.
  3. Load /.
  4. Wait for the visible links to prefetch.
  5. Click Route A.

Actual behavior

Clicking Route A still triggers route-specific loading work, such as a delayed /assets/a-*.js request, even though the route link was visible and had prefetched.

Expected behavior

A prefetched route navigation should be warm by the time the user clicks it. Route-specific client chunks and RSC decoding work needed for the navigation should already have been started or reused from the prefetch.

Environment

Notes

Router prefetch table uses route-local indexes

The generated router prefetch code builds a global ids array, but computes each route's indexes against that route's local module ID list. At runtime, those route-local indexes are used against the global ids array, which can point at earlier routes' chunks instead.

- Object.entries(path2moduleIds).forEach(([path, ids]) => {
-   path2idxs[path] = ids.map((id) => ids.indexOf(id))
+ Object.entries(path2moduleIds).forEach(([path, pathIds]) => {
+   path2idxs[path] = pathIds.map((id) => ids.indexOf(id))
  })

RSC prefetch response is not decoded until navigation

unstable_prefetchRsc caches the fetched response, but the prefetch path returns before calling createFromFetch. On navigation, Waku consumes the prefetched response and then creates elements for the first time. That means client module references in the Flight payload may still be resolved during click-time navigation.

A complete fix likely needs to decode/create the elements during prefetch, store them on the prefetched entry, and reuse those elements when the matching navigation consumes the prefetched entry.

Activity

  1. dai-shi commented on May 25, 2026

    @dai-shi
    Member
    • Production router prefetch code can preload the wrong client chunks.
    • RSC prefetch stores the response, but does not reuse decoded elements on navigation, so client module references can still be resolved at click time.

    As I understand it, the first one is the obvious bug we should fix now.
    But, the second one is optimization with a cost. And, I'm not sure if we should push it now.

    Can we just land the first one and take more time for the second one?

    So my request is split #2100 into two PRs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions