Unverified Commit f17694d6 authored by Andrew Clark's avatar Andrew Clark Committed by GitHub

Optimistic routing: client-side route prediction (#88965)

Based on:

- https://github.com/vercel/next.js/pull/88834
- https://github.com/vercel/next.js/pull/88989
- https://github.com/vercel/next.js/pull/88998

---

Adds optimistic routing, enabling the client to predict route structure
for URLs that haven't been prefetched yet. When navigating to a URL like
/blog/post-2, if we've previously learned the pattern from /blog/post-1,
we can predict the route structure without waiting for a server
response.

The client learns route patterns from server responses and builds a trie
indexed by URL parts. When a cache miss occurs, we check if the URL
matches a known pattern. If so, we create a synthetic cache entry from
the template, allowing immediate rendering of loading boundaries.

Static siblings (like /blog/featured alongside /blog/[slug]) are tracked
to avoid incorrect predictions — we only predict dynamic routes when
we're confident no static sibling matches.
parent 0e1b6d6a
...@@ -357,6 +357,8 @@ export function getDefineEnv({ ...@@ -357,6 +357,8 @@ export function getDefineEnv({
config.experimental.transitionIndicator ?? false, config.experimental.transitionIndicator ?? false,
'process.env.__NEXT_GESTURE_TRANSITION': 'process.env.__NEXT_GESTURE_TRANSITION':
config.experimental.gestureTransition ?? false, config.experimental.gestureTransition ?? false,
'process.env.__NEXT_OPTIMISTIC_ROUTING':
config.experimental.optimisticRouting ?? false,
'process.env.__NEXT_CACHE_LIFE': config.cacheLife, 'process.env.__NEXT_CACHE_LIFE': config.cacheLife,
'process.env.__NEXT_CLIENT_PARAM_PARSING_ORIGINS': 'process.env.__NEXT_CLIENT_PARAM_PARSING_ORIGINS':
config.experimental.clientParamParsingOrigins || [], config.experimental.clientParamParsingOrigins || [],
......
...@@ -318,6 +318,8 @@ export async function hydrate( ...@@ -318,6 +318,8 @@ export async function hydrate(
initialFlightData: initialRSCPayload.f, initialFlightData: initialRSCPayload.f,
initialCanonicalUrlParts: initialRSCPayload.c, initialCanonicalUrlParts: initialRSCPayload.c,
initialRenderedSearch: initialRSCPayload.q, initialRenderedSearch: initialRSCPayload.q,
initialCouldBeIntercepted: initialRSCPayload.i,
initialPrerendered: initialRSCPayload.S,
location: window.location, location: window.location,
}), }),
instrumentationHooks instrumentationHooks
......
...@@ -24,6 +24,7 @@ import { ...@@ -24,6 +24,7 @@ import {
dispatchAppRouterAction, dispatchAppRouterAction,
dispatchGestureState, dispatchGestureState,
} from './use-action-queue' } from './use-action-queue'
import { resetKnownRoutes } from './segment-cache/optimistic-routes'
import { FreshnessPolicy } from './router-reducer/ppr-navigations' import { FreshnessPolicy } from './router-reducer/ppr-navigations'
import { addBasePath } from '../add-base-path' import { addBasePath } from '../add-base-path'
import { isExternalURL } from './app-router-utils' import { isExternalURL } from './app-router-utils'
...@@ -456,6 +457,9 @@ export const publicAppRouterInstance: AppRouterInstance = { ...@@ -456,6 +457,9 @@ export const publicAppRouterInstance: AppRouterInstance = {
'hmrRefresh can only be used in development mode. Please use refresh instead.' 'hmrRefresh can only be used in development mode. Please use refresh instead.'
) )
} else { } else {
// Reset the known routes table so that route predictions are cleared
// when routes change during development.
resetKnownRoutes()
startTransition(() => { startTransition(() => {
dispatchAppRouterAction({ dispatchAppRouterAction({
type: ACTION_HMR_REFRESH, type: ACTION_HMR_REFRESH,
......
...@@ -7,6 +7,7 @@ import type { AppRouterState } from './router-reducer-types' ...@@ -7,6 +7,7 @@ import type { AppRouterState } from './router-reducer-types'
import { getFlightDataPartsFromPath } from '../../flight-data-helpers' import { getFlightDataPartsFromPath } from '../../flight-data-helpers'
import { createInitialCacheNodeForHydration } from './ppr-navigations' import { createInitialCacheNodeForHydration } from './ppr-navigations'
import { convertRootFlightRouterStateToRouteTree } from '../segment-cache/cache' import { convertRootFlightRouterStateToRouteTree } from '../segment-cache/cache'
import { discoverKnownRoute } from '../segment-cache/optimistic-routes'
import type { NormalizedSearch } from '../segment-cache/cache-key' import type { NormalizedSearch } from '../segment-cache/cache-key'
export interface InitialRouterStateParameters { export interface InitialRouterStateParameters {
...@@ -14,6 +15,8 @@ export interface InitialRouterStateParameters { ...@@ -14,6 +15,8 @@ export interface InitialRouterStateParameters {
initialCanonicalUrlParts: string[] initialCanonicalUrlParts: string[]
initialRenderedSearch: string initialRenderedSearch: string
initialFlightData: FlightDataPath[] initialFlightData: FlightDataPath[]
initialCouldBeIntercepted: boolean
initialPrerendered: boolean
location: Location | null location: Location | null
} }
...@@ -22,6 +25,8 @@ export function createInitialRouterState({ ...@@ -22,6 +25,8 @@ export function createInitialRouterState({
initialFlightData, initialFlightData,
initialCanonicalUrlParts, initialCanonicalUrlParts,
initialRenderedSearch, initialRenderedSearch,
initialCouldBeIntercepted,
initialPrerendered,
location, location,
}: InitialRouterStateParameters): AppRouterState { }: InitialRouterStateParameters): AppRouterState {
// When initialized on the server, the canonical URL is provided as an array of parts. // When initialized on the server, the canonical URL is provided as an array of parts.
...@@ -56,6 +61,7 @@ export function createInitialRouterState({ ...@@ -56,6 +61,7 @@ export function createInitialRouterState({
initialRenderedSearch as NormalizedSearch, initialRenderedSearch as NormalizedSearch,
acc acc
) )
const metadataVaryPath = acc.metadataVaryPath
const initialTask = createInitialCacheNodeForHydration( const initialTask = createInitialCacheNodeForHydration(
navigatedAt, navigatedAt,
initialRouteTree, initialRouteTree,
...@@ -63,6 +69,23 @@ export function createInitialRouterState({ ...@@ -63,6 +69,23 @@ export function createInitialRouterState({
initialHead initialHead
) )
// Learn the route pattern so we can predict it for future navigations.
// Only do this in the browser (location !== null) since route learning
// state doesn't persist from SSR to client.
if (location !== null && metadataVaryPath !== null) {
discoverKnownRoute(
Date.now(),
location.pathname,
null, // No pending entry
initialRouteTree,
metadataVaryPath,
initialCouldBeIntercepted,
canonicalUrl,
initialPrerendered,
false // hasDynamicRewrite
)
}
// NOTE: We intentionally don't check if any data needs to be fetched from the // NOTE: We intentionally don't check if any data needs to be fetched from the
// server. We assume the initial hydration payload is sufficient to render // server. We assume the initial hydration payload is sufficient to render
// the page. // the page.
...@@ -96,8 +119,8 @@ export function createInitialRouterState({ ...@@ -96,8 +119,8 @@ export function createInitialRouterState({
}, },
canonicalUrl, canonicalUrl,
renderedSearch: initialRenderedSearch, renderedSearch: initialRenderedSearch,
// the || operator is intentional, the pathname can be an empty string
nextUrl: nextUrl:
// the || operator is intentional, the pathname can be an empty string
(extractPathFromFlightRouterState(initialTree) || location?.pathname) ?? (extractPathFromFlightRouterState(initialTree) || location?.pathname) ??
null, null,
previousNextUrl: null, previousNextUrl: null,
......
...@@ -27,11 +27,15 @@ import { ...@@ -27,11 +27,15 @@ import {
import { import {
type RouteTree, type RouteTree,
type RefreshState, type RefreshState,
type FulfilledRouteCacheEntry,
convertReusedFlightRouterStateToRouteTree, convertReusedFlightRouterStateToRouteTree,
readSegmentCacheEntry, readSegmentCacheEntry,
waitForSegmentCacheEntry, waitForSegmentCacheEntry,
markRouteEntryAsDynamicRewrite,
invalidateRouteCacheEntries,
EntryStatus, EntryStatus,
} from '../segment-cache/cache' } from '../segment-cache/cache'
import { discoverKnownRoute } from '../segment-cache/optimistic-routes'
import type { NormalizedSearch } from '../segment-cache/cache-key' import type { NormalizedSearch } from '../segment-cache/cache-key'
import { import {
getRenderedSearchFromVaryPath, getRenderedSearchFromVaryPath,
...@@ -1110,6 +1114,25 @@ function createCacheNodeForSegment( ...@@ -1110,6 +1114,25 @@ function createCacheNodeForSegment(
} }
} }
if (process.env.__NEXT_OPTIMISTIC_ROUTING && isCachedHeadPartial) {
// TODO: When optimistic routing is enabled, don't block on waiting for
// the viewport to resolve. This is a temporary workaround until Vary
// Params are tracked when rendering the metadata. We'll fix it before
// this feature is stable. However, it's not a critical issue because 1)
// it will stream in eventually anyway 2) metadata is wrapped in an
// internal Suspense boundary, so is always non-blocking; this only
// affects the viewport node, which is meant to blocking, however... 3)
// before Segment Cache landed this wasn't always the case, anyway, so
// it's unlikely that many people are relying on this behavior. Still,
// will be fixed before stable. It's the very next step in the sequence of
// work on this project.
//
// This line of code works because the App Router treats `null` as
// "no renderable head available", rather than an empty head. React treats
// an empty string as empty.
cachedHead = ''
}
if (seedHead !== null) { if (seedHead !== null) {
if (isCachedHeadPartial) { if (isCachedHeadPartial) {
prefetchHead = cachedHead prefetchHead = cachedHead
...@@ -1194,7 +1217,12 @@ export function spawnDynamicRequests( ...@@ -1194,7 +1217,12 @@ export function spawnDynamicRequests(
primaryUrl: URL, primaryUrl: URL,
nextUrl: string | null, nextUrl: string | null,
freshnessPolicy: FreshnessPolicy, freshnessPolicy: FreshnessPolicy,
accumulation: NavigationRequestAccumulation accumulation: NavigationRequestAccumulation,
// The route cache entry used for this navigation, if it came from route
// prediction. Passed through so it can be marked as having a dynamic rewrite
// if the server returns a different pathname than expected (indicating
// dynamic rewrite behavior that varies by param value).
routeCacheEntry: FulfilledRouteCacheEntry | null
): void { ): void {
const dynamicRequestTree = task.dynamicRequestTree const dynamicRequestTree = task.dynamicRequestTree
if (dynamicRequestTree === null) { if (dynamicRequestTree === null) {
...@@ -1281,7 +1309,8 @@ export function spawnDynamicRequests( ...@@ -1281,7 +1309,8 @@ export function spawnDynamicRequests(
task, task,
nextUrl, nextUrl,
primaryRequestPromise, primaryRequestPromise,
refreshRequestPromises refreshRequestPromises,
routeCacheEntry
) )
// `finishNavigationTask` is responsible for error handling, so we can attach // `finishNavigationTask` is responsible for error handling, so we can attach
// noop callbacks to this promise. // noop callbacks to this promise.
...@@ -1294,7 +1323,8 @@ async function finishNavigationTask( ...@@ -1294,7 +1323,8 @@ async function finishNavigationTask(
primaryRequestPromise: ReturnType<typeof fetchMissingDynamicData>, primaryRequestPromise: ReturnType<typeof fetchMissingDynamicData>,
refreshRequestPromises: Array< refreshRequestPromises: Array<
ReturnType<typeof fetchMissingDynamicData> ReturnType<typeof fetchMissingDynamicData>
> | null > | null,
routeCacheEntry: FulfilledRouteCacheEntry | null
): Promise<void> { ): Promise<void> {
// Wait for all the requests to finish, or for the first one to fail. // Wait for all the requests to finish, or for the first one to fail.
let exitStatus = await waitForRequestsToFinish( let exitStatus = await waitForRequestsToFinish(
...@@ -1330,7 +1360,8 @@ async function finishNavigationTask( ...@@ -1330,7 +1360,8 @@ async function finishNavigationTask(
primaryRequestResult.url, primaryRequestResult.url,
nextUrl, nextUrl,
primaryRequestResult.seed, primaryRequestResult.seed,
task.route task.route,
routeCacheEntry
) )
return return
} }
...@@ -1350,7 +1381,8 @@ async function finishNavigationTask( ...@@ -1350,7 +1381,8 @@ async function finishNavigationTask(
primaryRequestResult.url, primaryRequestResult.url,
nextUrl, nextUrl,
primaryRequestResult.seed, primaryRequestResult.seed,
task.route task.route,
routeCacheEntry
) )
return return
} }
...@@ -1414,8 +1446,43 @@ function dispatchRetryDueToTreeMismatch( ...@@ -1414,8 +1446,43 @@ function dispatchRetryDueToTreeMismatch(
retryUrl: URL, retryUrl: URL,
retryNextUrl: string | null, retryNextUrl: string | null,
seed: NavigationSeed | null, seed: NavigationSeed | null,
baseTree: FlightRouterState baseTree: FlightRouterState,
// The route cache entry used for this navigation, if it came from route
// prediction. If the navigation results in a mismatch, we mark it as having
// a dynamic rewrite so future predictions bail out.
routeCacheEntry: FulfilledRouteCacheEntry | null
) { ) {
// If the navigation used a route prediction, mark it as having a dynamic
// rewrite since it resulted in a mismatch.
if (routeCacheEntry !== null) {
markRouteEntryAsDynamicRewrite(routeCacheEntry)
} else if (seed !== null) {
// Even without a direct reference to the route cache entry, we can still
// mark the route as having a dynamic rewrite by traversing the known route
// tree. This handles cases where the navigation didn't originate from a
// route prediction, but still needs to mark the pattern.
const metadataVaryPath = seed.metadataVaryPath
if (metadataVaryPath !== null) {
const now = Date.now()
discoverKnownRoute(
now,
retryUrl.pathname,
null,
seed.routeTree,
metadataVaryPath,
false, // couldBeIntercepted - doesn't matter, we're just marking hasDynamicRewrite
createHrefFromUrl(retryUrl),
false, // isPPREnabled - doesn't matter, we're just marking hasDynamicRewrite
true // hasDynamicRewrite
)
}
}
// Invalidate all route cache entries. Other entries may have been derived
// from the template before we knew it had a dynamic rewrite. This also
// triggers re-prefetching of visible links.
invalidateRouteCacheEntries(retryNextUrl, baseTree)
// If this is the second time in a row that a navigation resulted in a // If this is the second time in a row that a navigation resulted in a
// mismatch, fall back to a hard (MPA) refresh. // mismatch, fall back to a hard (MPA) refresh.
isHardRetry = isHardRetry || previousNavigationDidMismatch isHardRetry = isHardRetry || previousNavigationDidMismatch
......
...@@ -72,6 +72,11 @@ export function refreshDynamicData( ...@@ -72,6 +72,11 @@ export function refreshDynamicData(
nextUrlForRefresh, nextUrlForRefresh,
shouldScroll, shouldScroll,
navigateType, navigateType,
null,
// Refresh navigations don't use route prediction, so there's no route
// cache entry to mark as having a dynamic rewrite on mismatch. If a
// mismatch occurs, the retry handler will traverse the known route tree
// to find and mark the entry.
null null
) )
} }
...@@ -76,7 +76,12 @@ export function restoreReducer( ...@@ -76,7 +76,12 @@ export function restoreReducer(
restoredUrl, restoredUrl,
restoredNextUrl, restoredNextUrl,
FreshnessPolicy.HistoryTraversal, FreshnessPolicy.HistoryTraversal,
accumulation accumulation,
// History traversal doesn't use route prediction, so there's no route
// cache entry to mark as having a dynamic rewrite on mismatch. If a
// mismatch occurs, the retry handler will traverse the known route tree
// to find and mark the entry.
null
) )
return completeTraverseNavigation( return completeTraverseNavigation(
state, state,
......
...@@ -54,6 +54,7 @@ import { ...@@ -54,6 +54,7 @@ import {
navigateToKnownRoute, navigateToKnownRoute,
navigate, navigate,
} from '../../segment-cache/navigation' } from '../../segment-cache/navigation'
import { discoverKnownRoute } from '../../segment-cache/optimistic-routes'
import type { NormalizedSearch } from '../../segment-cache/cache-key' import type { NormalizedSearch } from '../../segment-cache/cache-key'
import { import {
ActionDidNotRevalidate, ActionDidNotRevalidate,
...@@ -92,6 +93,7 @@ type FetchServerActionResult = { ...@@ -92,6 +93,7 @@ type FetchServerActionResult = {
actionFlightData: NormalizedFlightData[] | string | undefined actionFlightData: NormalizedFlightData[] | string | undefined
actionFlightDataRenderedSearch: NormalizedSearch | undefined actionFlightDataRenderedSearch: NormalizedSearch | undefined
isPrerender: boolean isPrerender: boolean
couldBeIntercepted: boolean
} }
async function fetchServerAction( async function fetchServerAction(
...@@ -209,6 +211,7 @@ async function fetchServerAction( ...@@ -209,6 +211,7 @@ async function fetchServerAction(
let actionResult: FetchServerActionResult['actionResult'] let actionResult: FetchServerActionResult['actionResult']
let actionFlightData: FetchServerActionResult['actionFlightData'] let actionFlightData: FetchServerActionResult['actionFlightData']
let actionFlightDataRenderedSearch: FetchServerActionResult['actionFlightDataRenderedSearch'] let actionFlightDataRenderedSearch: FetchServerActionResult['actionFlightDataRenderedSearch']
let couldBeIntercepted: boolean = false
if (isRscResponse) { if (isRscResponse) {
const response: ActionFlightResponse = await createFromFetch( const response: ActionFlightResponse = await createFromFetch(
...@@ -223,6 +226,7 @@ async function fetchServerAction( ...@@ -223,6 +226,7 @@ async function fetchServerAction(
// An internal redirect can send an RSC response, but does not have a useful `actionResult`. // An internal redirect can send an RSC response, but does not have a useful `actionResult`.
actionResult = redirectLocation ? undefined : response.a actionResult = redirectLocation ? undefined : response.a
couldBeIntercepted = response.i
const maybeFlightData = normalizeFlightData(response.f) const maybeFlightData = normalizeFlightData(response.f)
if (maybeFlightData !== '') { if (maybeFlightData !== '') {
actionFlightData = maybeFlightData actionFlightData = maybeFlightData
...@@ -243,6 +247,7 @@ async function fetchServerAction( ...@@ -243,6 +247,7 @@ async function fetchServerAction(
redirectType, redirectType,
revalidationKind, revalidationKind,
isPrerender, isPrerender,
couldBeIntercepted,
} }
} }
...@@ -279,6 +284,8 @@ export function serverActionReducer( ...@@ -279,6 +284,8 @@ export function serverActionReducer(
actionFlightDataRenderedSearch: flightDataRenderedSearch, actionFlightDataRenderedSearch: flightDataRenderedSearch,
redirectLocation, redirectLocation,
redirectType, redirectType,
isPrerender,
couldBeIntercepted,
}) => { }) => {
if (revalidationKind !== ActionDidNotRevalidate) { if (revalidationKind !== ActionDidNotRevalidate) {
// There was either a revalidation or a refresh, or maybe both. // There was either a revalidation or a refresh, or maybe both.
...@@ -414,6 +421,23 @@ export function serverActionReducer( ...@@ -414,6 +421,23 @@ export function serverActionReducer(
flightDataRenderedSearch flightDataRenderedSearch
) )
const now = Date.now() const now = Date.now()
// Learn the route pattern so we can predict it for future navigations.
const metadataVaryPath = redirectSeed.metadataVaryPath
if (metadataVaryPath !== null) {
discoverKnownRoute(
now,
redirectUrl.pathname,
null, // No pending entry
redirectSeed.routeTree,
metadataVaryPath,
couldBeIntercepted,
redirectCanonicalUrl,
isPrerender,
false // hasDynamicRewrite
)
}
return navigateToKnownRoute( return navigateToKnownRoute(
now, now,
state, state,
...@@ -428,6 +452,11 @@ export function serverActionReducer( ...@@ -428,6 +452,11 @@ export function serverActionReducer(
nextUrl, nextUrl,
shouldScroll, shouldScroll,
navigateType, navigateType,
null,
// Server action redirects don't use route prediction - we already
// have the route tree from the server response. If a mismatch occurs
// during dynamic data fetch, the retry handler will traverse the
// known route tree to mark the entry as having a dynamic rewrite.
null null
) )
} }
......
...@@ -57,6 +57,10 @@ export function serverPatchReducer( ...@@ -57,6 +57,10 @@ export function serverPatchReducer(
retryNextUrl, retryNextUrl,
shouldScroll, shouldScroll,
navigateType, navigateType,
null,
// Server patch (retry) navigations don't use route prediction. This is
// typically a retry after a previous mismatch, so the route was already
// marked as having a dynamic rewrite when the mismatch was detected.
null null
) )
} }
...@@ -17,11 +17,12 @@ import { createHrefFromUrl } from '../router-reducer/create-href-from-url' ...@@ -17,11 +17,12 @@ import { createHrefFromUrl } from '../router-reducer/create-href-from-url'
import { import {
EntryStatus, EntryStatus,
readRouteCacheEntry, readRouteCacheEntry,
requestOptimisticRouteCacheEntry, deprecated_requestOptimisticRouteCacheEntry,
convertRootFlightRouterStateToRouteTree, convertRootFlightRouterStateToRouteTree,
type RouteTree, type RouteTree,
type FulfilledRouteCacheEntry, type FulfilledRouteCacheEntry,
} from './cache' } from './cache'
import { discoverKnownRoute } from './optimistic-routes'
import { createCacheKey, type NormalizedSearch } from './cache-key' import { createCacheKey, type NormalizedSearch } from './cache-key'
import type { PageVaryPath } from './vary-path' import type { PageVaryPath } from './vary-path'
import type { AppRouterState } from '../router-reducer/router-reducer-types' import type { AppRouterState } from '../router-reducer/router-reducer-types'
...@@ -72,7 +73,9 @@ export function navigate( ...@@ -72,7 +73,9 @@ export function navigate(
} }
// There was no matching route tree in the cache. Let's see if we can // There was no matching route tree in the cache. Let's see if we can
// construct an "optimistic" route tree. // construct an "optimistic" route tree using the deprecated search-params
// based matching. This is only used when the new optimisticRouting flag is
// disabled.
// //
// Do not construct an optimistic route tree if there was a cache hit, but // Do not construct an optimistic route tree if there was a cache hit, but
// the entry has a rejected status, since it may have been rejected due to a // the entry has a rejected status, since it may have been rejected due to a
...@@ -80,29 +83,36 @@ export function navigate( ...@@ -80,29 +83,36 @@ export function navigate(
// //
// TODO: There are multiple reasons a prefetch might be rejected; we should // TODO: There are multiple reasons a prefetch might be rejected; we should
// track them explicitly and choose what to do here based on that. // track them explicitly and choose what to do here based on that.
if (route === null || route.status !== EntryStatus.Rejected) { if (!process.env.__NEXT_OPTIMISTIC_ROUTING) {
const optimisticRoute = requestOptimisticRouteCacheEntry(now, url, nextUrl) if (route === null || route.status !== EntryStatus.Rejected) {
if (optimisticRoute !== null) { const optimisticRoute = deprecated_requestOptimisticRouteCacheEntry(
// We have an optimistic route tree. Proceed with the normal flow.
return navigateUsingPrefetchedRouteTree(
now, now,
state,
url, url,
currentUrl, nextUrl
currentRenderedSearch,
nextUrl,
currentCacheNode,
currentFlightRouterState,
freshnessPolicy,
shouldScroll,
navigateType,
optimisticRoute
) )
if (optimisticRoute !== null) {
// We have an optimistic route tree. Proceed with the normal flow.
return navigateUsingPrefetchedRouteTree(
now,
state,
url,
currentUrl,
currentRenderedSearch,
nextUrl,
currentCacheNode,
currentFlightRouterState,
freshnessPolicy,
shouldScroll,
navigateType,
optimisticRoute
)
}
} }
} }
// There's no matching prefetch for this route in the cache. // There's no matching prefetch for this route in the cache. We must lazily
// TODO: If this is an optimistic navigation, instead of performing a // fetch it from the server before we can perform the navigation.
// TODO: If this is an gesture navigation, instead of performing a
// dynamic request, we should do a runtime prefetch. // dynamic request, we should do a runtime prefetch.
return navigateToUnknownRoute( return navigateToUnknownRoute(
now, now,
...@@ -136,7 +146,19 @@ export function navigateToKnownRoute( ...@@ -136,7 +146,19 @@ export function navigateToKnownRoute(
nextUrl: string | null, nextUrl: string | null,
shouldScroll: boolean, shouldScroll: boolean,
navigateType: 'push' | 'replace', navigateType: 'push' | 'replace',
debugInfo: Array<unknown> | null debugInfo: Array<unknown> | null,
// The route cache entry used for this navigation, if it came from route
// prediction. Passed through so it can be marked as having a dynamic rewrite
// if the server returns a different pathname (indicating dynamic rewrite
// behavior).
//
// When null, the navigation did not use route prediction - either because
// the route was already fully cached, or it's a navigation that doesn't
// involve prediction (refresh, history traversal, server action, etc.).
// In these cases, if a mismatch occurs, we still mark the route as having a
// dynamic rewrite by traversing the known route tree (see
// dispatchRetryDueToTreeMismatch).
routeCacheEntry: FulfilledRouteCacheEntry | null
): AppRouterState { ): AppRouterState {
// A version of navigate() that accepts the target route tree as an argument // A version of navigate() that accepts the target route tree as an argument
// rather than reading it from the prefetch cache. // rather than reading it from the prefetch cache.
...@@ -178,11 +200,15 @@ export function navigateToKnownRoute( ...@@ -178,11 +200,15 @@ export function navigateToKnownRoute(
accumulation accumulation
) )
if (task !== null) { if (task !== null) {
// Skip spawning dynamic requests for gesture navigations. Only the
// cached UI will be shown. The gesture state will be discarded when
// the canonical navigation completes.
if (freshnessPolicy !== FreshnessPolicy.Gesture) { if (freshnessPolicy !== FreshnessPolicy.Gesture) {
spawnDynamicRequests(task, url, nextUrl, freshnessPolicy, accumulation) spawnDynamicRequests(
task,
url,
nextUrl,
freshnessPolicy,
accumulation,
routeCacheEntry
)
} }
return completeSoftNavigation( return completeSoftNavigation(
state, state,
...@@ -240,7 +266,8 @@ function navigateUsingPrefetchedRouteTree( ...@@ -240,7 +266,8 @@ function navigateUsingPrefetchedRouteTree(
nextUrl, nextUrl,
shouldScroll, shouldScroll,
navigateType, navigateType,
null null,
route
) )
} }
...@@ -310,7 +337,14 @@ async function navigateToUnknownRoute( ...@@ -310,7 +337,14 @@ async function navigateToUnknownRoute(
return completeHardNavigation(state, redirectUrl, navigateType) return completeHardNavigation(state, redirectUrl, navigateType)
} }
const { flightData, canonicalUrl, renderedSearch, debugInfo } = result const {
flightData,
canonicalUrl,
renderedSearch,
couldBeIntercepted,
prerendered,
debugInfo,
} = result
// Since the response format of dynamic requests and prefetches is slightly // Since the response format of dynamic requests and prefetches is slightly
// different, we'll need to massage the data a bit. Create FlightRouterState // different, we'll need to massage the data a bit. Create FlightRouterState
...@@ -321,6 +355,26 @@ async function navigateToUnknownRoute( ...@@ -321,6 +355,26 @@ async function navigateToUnknownRoute(
renderedSearch renderedSearch
) )
// Learn the route pattern so we can predict it for future navigations.
// hasDynamicRewrite is false because this is a fresh navigation to an
// unknown route - any rewrite detection happens during the traversal inside
// discoverKnownRoute. The hasDynamicRewrite param is only set to true when
// retrying after a tree mismatch (see dispatchRetryDueToTreeMismatch).
const metadataVaryPath = navigationSeed.metadataVaryPath
if (metadataVaryPath !== null) {
discoverKnownRoute(
now,
url.pathname,
null, // No pending entry
navigationSeed.routeTree,
metadataVaryPath,
couldBeIntercepted,
createHrefFromUrl(canonicalUrl),
prerendered,
false // hasDynamicRewrite - not a retry, rewrite detection happens during traversal
)
}
return navigateToKnownRoute( return navigateToKnownRoute(
now, now,
state, state,
...@@ -335,7 +389,12 @@ async function navigateToUnknownRoute( ...@@ -335,7 +389,12 @@ async function navigateToUnknownRoute(
nextUrl, nextUrl,
shouldScroll, shouldScroll,
navigateType, navigateType,
debugInfo debugInfo,
// Unknown route navigations don't use route prediction - the route tree
// came directly from the server. If a mismatch occurs during dynamic data
// fetch, the retry handler will traverse the known route tree to mark the
// entry as having a dynamic rewrite.
null
) )
} }
......
...@@ -1720,6 +1720,8 @@ function App<T>({ ...@@ -1720,6 +1720,8 @@ function App<T>({
initialFlightData: response.f, initialFlightData: response.f,
initialCanonicalUrlParts: response.c, initialCanonicalUrlParts: response.c,
initialRenderedSearch: response.q, initialRenderedSearch: response.q,
initialCouldBeIntercepted: response.i,
initialPrerendered: response.S,
// location is not initialized in the SSR render // location is not initialized in the SSR render
// it's set to window.location during hydration // it's set to window.location during hydration
location: null, location: null,
...@@ -1783,6 +1785,8 @@ function ErrorApp<T>({ ...@@ -1783,6 +1785,8 @@ function ErrorApp<T>({
initialFlightData: response.f, initialFlightData: response.f,
initialCanonicalUrlParts: response.c, initialCanonicalUrlParts: response.c,
initialRenderedSearch: response.q, initialRenderedSearch: response.q,
initialCouldBeIntercepted: response.i,
initialPrerendered: response.S,
// location is not initialized in the SSR render // location is not initialized in the SSR render
// it's set to window.location during hydration // it's set to window.location during hydration
location: null, location: null,
......
'use client'
import { Suspense } from 'react'
import { useParams } from 'next/navigation'
function LoadingWithSlug() {
const params = useParams<{ slug: string }>()
return <p id="loading-message">Loading {params.slug}...</p>
}
export default function Loading() {
return (
<div id="loading-boundary">
<Suspense fallback={<p id="loading-message">Loading...</p>}>
<LoadingWithSlug />
</Suspense>
</div>
)
}
import { connection } from 'next/server'
export default async function ActualPage({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
await connection()
return (
<div id="actual-page">
<h1>Actual page</h1>
<p data-slug={slug}>Slug: {slug}</p>
</div>
)
}
'use client'
import { Suspense } from 'react'
import { useParams } from 'next/navigation'
function LoadingWithSlug() {
const params = useParams<{ slug: string }>()
return <p id="loading-message">Loading {params.slug}...</p>
}
export default function Loading() {
return (
<div id="loading-boundary">
<Suspense fallback="Loading...">
<LoadingWithSlug />
</Suspense>
</div>
)
}
import { connection } from 'next/server'
import Link from 'next/link'
export default async function BlogPost({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
// Make this component dynamic
await connection()
return (
<div id="blog-post">
<h1 id="post-title">Blog Post: {slug}</h1>
<p id="post-slug">Slug: {slug}</p>
<Link href="/" id="back-link">
Back to home
</Link>
</div>
)
}
import Link from 'next/link'
// This is a static sibling to /blog/[slug]. Route prediction should NOT
// apply to this route - it should be resolved via a tree prefetch, not
// by matching the dynamic [slug] pattern.
export default function FeaturedPage() {
return (
<div id="featured-page">
<h1 id="featured-title">Featured Blog Post</h1>
<p id="featured-description">
This is a static route that exists alongside the dynamic /blog/[slug]
route.
</p>
<Link href="/" id="back-link">
Back to home
</Link>
</div>
)
}
'use client'
import { Suspense } from 'react'
import { useParams } from 'next/navigation'
function LoadingWithParams() {
const params = useParams<{ slug?: string[] }>()
const path = params.slug ? params.slug.join('/') : '(index)'
return <p id="loading-message">Loading docs {path}...</p>
}
export default function Loading() {
return (
<div id="loading-boundary">
<Suspense fallback={<p id="loading-message">Loading docs...</p>}>
<LoadingWithParams />
</Suspense>
</div>
)
}
import { connection } from 'next/server'
import Link from 'next/link'
export default async function DocsPage({
params,
}: {
params: Promise<{ slug?: string[] }>
}) {
const { slug } = await params
await connection()
const path = slug ? slug.join('/') : '(index)'
return (
<div id="docs-page">
<h1 id="docs-title">Docs: {path}</h1>
<p id="docs-path">Path: {path}</p>
<Link href="/" id="back-link">
Back to home
</Link>
</div>
)
}
'use client'
import { Suspense } from 'react'
import { useParams } from 'next/navigation'
function LoadingWithParams() {
const params = useParams<{ path: string[] }>()
const filePath = params.path.join('/')
return <p id="loading-message">Loading file {filePath}...</p>
}
export default function Loading() {
return (
<div id="loading-boundary">
<Suspense fallback={<p id="loading-message">Loading file...</p>}>
<LoadingWithParams />
</Suspense>
</div>
)
}
import { connection } from 'next/server'
import Link from 'next/link'
export default async function FilesPage({
params,
}: {
params: Promise<{ path: string[] }>
}) {
const { path } = await params
await connection()
const filePath = path.join('/')
return (
<div id="files-page">
<h1 id="files-title">File: {filePath}</h1>
<p id="files-path">Path: {filePath}</p>
<Link href="/" id="back-link">
Back to home
</Link>
</div>
)
}
import { ReactNode, Suspense } from 'react'
import { ParamsHistory } from '../components/params-history'
export default function Root({ children }: { children: ReactNode }) {
return (
<html>
<body>
<Suspense fallback={null}>
<ParamsHistory />
</Suspense>
{children}
</body>
</html>
)
}
import { LinkAccordion } from '../components/link-accordion'
export default function Home() {
return (
<div>
<h1>Optimistic Routing Test</h1>
<p>
This test verifies that route prediction works correctly. When a route
pattern is learned from one URL, navigating to a different URL with the
same pattern should show the loading state instantly.
</p>
<h2>Basic Dynamic Route</h2>
<ul>
<li>
<LinkAccordion href="/blog/post-1">Blog Post 1</LinkAccordion>
</li>
<li>
<LinkAccordion href="/blog/post-2" prefetch={false}>
Blog Post 2 (prefetch disabled)
</LinkAccordion>
</li>
<li>
<LinkAccordion href="/blog/post-3" prefetch={false}>
Blog Post 3 (prefetch disabled)
</LinkAccordion>
</li>
</ul>
<h2>Nested Dynamic Route</h2>
<ul>
<li>
<LinkAccordion href="/products/electronics/phone-1">
Electronics - Phone 1
</LinkAccordion>
</li>
<li>
<LinkAccordion href="/products/electronics/phone-2" prefetch={false}>
Electronics - Phone 2 (prefetch disabled)
</LinkAccordion>
</li>
<li>
<LinkAccordion href="/products/clothing/shirt-1" prefetch={false}>
Clothing - Shirt 1 (prefetch disabled)
</LinkAccordion>
</li>
</ul>
<h2>Optional Catch-All Route</h2>
<ul>
<li>
<LinkAccordion href="/docs">Docs Index</LinkAccordion>
</li>
<li>
<LinkAccordion href="/docs/intro">Docs Intro</LinkAccordion>
</li>
<li>
<LinkAccordion href="/docs/guide/getting-started" prefetch={false}>
Docs Guide - Getting Started (prefetch disabled)
</LinkAccordion>
</li>
</ul>
<h2>Required Catch-All Route</h2>
<ul>
<li>
<LinkAccordion href="/files/documents/report.pdf">
Files - Report
</LinkAccordion>
</li>
<li>
<LinkAccordion href="/files/images/photo.jpg" prefetch={false}>
Files - Photo (prefetch disabled)
</LinkAccordion>
</li>
<li>
<LinkAccordion href="/files/a/b/c/d" prefetch={false}>
Files - Deep Path (prefetch disabled)
</LinkAccordion>
</li>
</ul>
<h2>Static Sibling Detection</h2>
<ul>
<li>
<LinkAccordion href="/blog/featured" prefetch={false}>
Featured (static sibling, prefetch disabled)
</LinkAccordion>
</li>
</ul>
<h2>Rewrite Detection (Route Params)</h2>
<p>
These URLs are rewritten by proxy to /actual/[slug]. The route should be
marked as having a dynamic rewrite since the URL doesn&apos;t match the
route structure.
</p>
<ul>
<li>
<LinkAccordion href="/rewritten/first">
Rewritten First (learns pattern, marks as dynamic rewrite)
</LinkAccordion>
</li>
<li>
<LinkAccordion href="/rewritten/second" prefetch={false}>
Rewritten Second (should not use cached pattern)
</LinkAccordion>
</li>
</ul>
<h2>Rewrite Detection (Search Params)</h2>
<p>
These URLs are rewritten based on search params. /search-rewrite?v=X
becomes /rewrite-target?content=X. Since the page is static, if we
incorrectly use a cached pattern, we&apos;d show wrong content.
</p>
<ul>
<li>
<LinkAccordion href="/search-rewrite?v=alpha">
Search Rewrite Alpha (v=alpha → content=alpha)
</LinkAccordion>
</li>
<li>
<LinkAccordion href="/search-rewrite?v=beta" prefetch={false}>
Search Rewrite Beta (v=beta → content=beta)
</LinkAccordion>
</li>
</ul>
</div>
)
}
'use client'
import { Suspense } from 'react'
import { useParams } from 'next/navigation'
function LoadingWithParams() {
const params = useParams<{ category: string; id: string }>()
return (
<p id="loading-message">
Loading {params.category}/{params.id}...
</p>
)
}
export default function Loading() {
return (
<div id="loading-boundary">
<Suspense fallback={<p id="loading-message">Loading product...</p>}>
<LoadingWithParams />
</Suspense>
</div>
)
}
import { connection } from 'next/server'
import Link from 'next/link'
export default async function ProductPage({
params,
}: {
params: Promise<{ category: string; id: string }>
}) {
const { category, id } = await params
await connection()
return (
<div id="product-page">
<h1 id="product-title">
Product: {category}/{id}
</h1>
<p id="product-category">Category: {category}</p>
<p id="product-id">ID: {id}</p>
<Link href="/" id="back-link">
Back to home
</Link>
</div>
)
}
// Fully static page - no dynamic data access
export default function RewriteAlphaPage() {
return (
<div id="rewrite-target-page">
<h1>Rewrite Target</h1>
<p id="rewrite-content" data-content="alpha">
Content: alpha
</p>
</div>
)
}
// Fully static page - no dynamic data access
export default function RewriteBetaPage() {
return (
<div id="rewrite-target-page">
<h1>Rewrite Target</h1>
<p id="rewrite-content" data-content="beta">
Content: beta
</p>
</div>
)
}
'use client'
import Link, { type LinkProps } from 'next/link'
import { useState } from 'react'
export function LinkAccordion({
href,
children,
prefetch,
}: {
href: LinkProps['href']
children: React.ReactNode
prefetch?: LinkProps['prefetch']
}) {
// This component controls when prefetching happens by hiding the Link until
// the checkbox is clicked. Prefetch triggers when the Link enters the viewport.
const [isVisible, setIsVisible] = useState(false)
return (
<>
<input
type="checkbox"
checked={isVisible}
onChange={() => setIsVisible(!isVisible)}
data-link-accordion={href}
/>
{isVisible ? (
<Link href={href} prefetch={prefetch}>
{children}
</Link>
) : (
`${children} (link is hidden)`
)}
</>
)
}
'use client'
import { useState } from 'react'
import { useParams } from 'next/navigation'
/**
* Accumulates all param values rendered throughout the app's lifetime.
* Uses the setState-in-render pattern to capture changes synchronously,
* before React commits. This catches any intermediate/wrong params that
* might flash briefly due to incorrect route prediction.
*/
export function ParamsHistory() {
const params = useParams()
const paramsJson = JSON.stringify(params)
const [history, setHistory] = useState<string[]>([paramsJson])
const [prevParams, setPrevParams] = useState(paramsJson)
// setState-in-render pattern: update state synchronously during render
// if the params have changed. This captures intermediate states.
if (paramsJson !== prevParams) {
setPrevParams(paramsJson)
setHistory((prev) => [...prev, paramsJson])
}
return (
<div
id="params-history"
data-history={JSON.stringify(history)}
style={{
padding: '8px',
marginTop: '16px',
background: '#f5f5f5',
borderRadius: '4px',
fontSize: '12px',
fontFamily: 'monospace',
}}
>
<div style={{ fontWeight: 'bold', marginBottom: '4px' }}>
Params History (debug)
</div>
<div>Current: {paramsJson}</div>
<div style={{ marginTop: '4px' }}>
History:{' '}
{history.map((h, i) => (
<span key={i}>
{i > 0 && ' → '}
{h}
</span>
))}
</div>
</div>
)
}
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
cacheComponents: true,
experimental: {
optimisticRouting: true,
},
productionBrowserSourceMaps: true,
}
module.exports = nextConfig
This diff is collapsed.
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
export function proxy(request: NextRequest) {
const pathname = request.nextUrl.pathname
// Rewrite /rewritten/[slug] to /actual/[slug]
// This creates a mismatch between URL and route structure that should
// mark the route as having a dynamic rewrite.
if (pathname.startsWith('/rewritten/')) {
const slug = pathname.replace('/rewritten/', '')
const url = request.nextUrl.clone()
url.pathname = `/actual/${slug}`
return NextResponse.rewrite(url)
}
// Rewrite /search-rewrite?v=alpha to /rewrite-alpha
// Rewrite /search-rewrite?v=beta to /rewrite-beta
// This tests that search param rewrites are correctly detected.
// The destination pages are fully static, so if we incorrectly use a cached
// pattern, we'd show the wrong content.
if (pathname === '/search-rewrite') {
const v = request.nextUrl.searchParams.get('v')
const url = request.nextUrl.clone()
url.pathname = v === 'beta' ? '/rewrite-beta' : '/rewrite-alpha'
url.searchParams.delete('v')
return NextResponse.rewrite(url)
}
return NextResponse.next()
}
export const config = {
matcher: ['/rewritten/:path*', '/search-rewrite'],
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment