Router Reducer

Copyfunction clientReducer(
  state: ReadonlyReducerState,
  action: ReducerActions
): ReducerState {
  switch (action.type) {
    case ACTION_NAVIGATE: {
      return navigateReducer(state, action)
    }
    case ACTION_SERVER_PATCH: {
      return serverPatchReducer(state, action)
    }
    case ACTION_RESTORE: {
      return restoreReducer(state, action)
    }
    case ACTION_REFRESH: {
      return refreshReducer(state, action)
    }
    case ACTION_HMR_REFRESH: {
      if (process.env.NODE_ENV === 'development') {
        const { hmrRefreshReducer } =
          require('./reducers/hmr-refresh-reducer') as typeof import('./reducers/hmr-refresh-reducer')
        return hmrRefreshReducer(state, action)
      } else {
        throw new Error(
          'hmrRefresh can only be used in development mode. Please use refresh instead.'
        )
      }
    }
    case ACTION_SERVER_ACTION: {
      return serverActionReducer(state, action)
    }
    default:
      throw new Error('Unknown action')
  }
}

Copyexport function navigate(
  href: string,
  navigateType: NavigateAction['navigateType'],
  scrollBehavior: ScrollBehavior,
  linkInstanceRef: LinkInstance | null,
  transitionTypes: string[] | undefined,
  prefetchIntent: RouterTransitionPrefetchIntent | null
): void {
  if (isJavaScriptURLString(href)) {
    throw new Error(
      'Next.js has blocked a javascript: URL as a security precaution.'
    )
  }
 
  startTransition(() => {
    if (transitionTypes) {
      for (const type of transitionTypes) {
        addTransitionType(type)
      }
    }
 
    const url = new URL(addBasePath(href), location.href)
    if (process.env.__NEXT_APP_NAV_FAIL_HANDLING) {
      window.next.__pendingUrl = url
    }
 
    setLinkForCurrentNavigation(linkInstanceRef)
    startRouterTransition(
      href,
      navigateType,
      getRequiredAppRouterState().tree,
      prefetchIntent
    )
 
    dispatchAppRouterAction({
      type: ACTION_NAVIGATE,
      url,
      isExternalUrl: isExternalURL(url),
      locationSearch: location.search,
      scrollBehavior,
      navigateType,
    })
  })
}

Copyexport function hmrRefresh(): void {
  if (process.env.NODE_ENV !== 'development') {
    throw new Error(
      'hmrRefresh can only be used in development mode. Please use refresh instead.'
    )
  } else {
    resetKnownRoutes()
    let signal: AbortSignal | undefined
    if (process.env.__NEXT_SERVER_COMPONENTS_HMR_CANCELLATION) {
      activeHmrRefreshController?.abort()
      activeHmrRefreshController = new AbortController()
      signal = activeHmrRefreshController.signal
    }
    startTransition(() => {
      dispatchAppRouterAction({
        type: ACTION_HMR_REFRESH,
        signal,
      })
    })
  }
}

Copyexport function createInitialRouterState({
  navigatedAt,
  initialRSCPayload,
  initialFlightStreamForCache,
  location,
}: InitialRouterStateParameters): AppRouterState {
  const {
    c: initialCanonicalUrlParts,
    t: initialTransportData,
    q: initialRenderedSearch,
    i: initialCouldBeIntercepted,
    S: initialSupportsPerSegmentPrefetching,
    s: initialStaleTime,
    l: initialStaticStageByteLength,
    r: initialRootVaryParams,
    p: initialRuntimePrefetchStream,
    d: initialDynamicStaleTimeSeconds,
  } = initialRSCPayload
 
  // When initialized on the server, the canonical URL is provided as an array of parts.
  // This is to ensure that when the RSC payload streamed to the client, crawlers don't interpret it
  // as a URL that should be crawled.
  const initialCanonicalUrl = initialCanonicalUrlParts.join('/')
 
  // The initial router state tree, derived from the transport tree.
  const initialTree = transportNodeToFlightRouterState(
    initialTransportData.t,
    initialRenderedSearch
  )
 

Copyconst initialSeed = createNavigationSeed(
  navigatedAt,
  // There's no base tree to overlay onto; the initial payload is a full
  // render from the root.
  null,
  initialTransportData,
  // The initial payload may still be streaming in while we hydrate, so its
  // vary params can't be drained here; they decode as null. The
  // segment-cache write below re-decodes the transport data with the
  // payload's root params once the stale time has resolved.
  null,
  // Same for partiality: only segment-cache writes consume it, and the
  // write below re-decodes with the payload's actual response-level value.
  // Pass the conservative value here.
  true,
  // The initial payload always includes the param values in the tree
  // (fallback shells are patched with the parsed values before this runs —
  // see createInitialRSCPayloadFromFallbackPrerender), so there's no
  // pathname to parse them from.
  null,
  initialRenderedSearch,
  null,
  initialDynamicStaleTimeSeconds ?? UnknownDynamicStaleTime
)
const initialRoot = initialSeed.root
const initialNavigation = createInitialRenderTreeForHydration(
  navigatedAt,
  initialRoot,
  initialSeed.dynamicStaleAt
)
 
// The following only applies in the browser (location !== null) since neither
// route learning nor segment cache state persists from SSR to client.
if (location !== null) {
  // Learn the route pattern so we can predict it for future navigations.
  discoverKnownRoute(
    Date.now(),
    location.pathname,
    location.search as NormalizedSearch,
    null, // nextUrl — initial render is never an interception
    null, // No pending entry
    initialRoot,
    initialCouldBeIntercepted,
    canonicalUrl,
    initialSeed.renderedSearch,
    initialSupportsPerSegmentPrefetching,
    false // hasDynamicRewrite
  )

Copyif (initialStaleTime !== undefined) {
  if (
    initialStaticStageByteLength !== undefined &&
    initialFlightStreamForCache != null
  ) {
    // Partially static page — truncate the cloned Flight stream at the
    // static stage byte boundary, decode, and cache the static subset.
    // Promise.resolve wraps the Flight-deserialized thenable into a
    // native Promise so we can chain `.then` on it safely.
    Promise.resolve(initialStaticStageByteLength)
      .then(async (byteLength) => {
        if (byteLength === 0) {
          initialFlightStreamForCache.cancel()
          return
        }
        const staticStageResponse =
          await decodeStageUntilBoundary<InitialRSCPayload>(
            initialFlightStreamForCache,
            byteLength,
            undefined
          )
        if (staticStageResponse === null) {
          return
        }
        spawnStaticStageCacheWrite(
          Date.now(),
          staticStageResponse,
          true, // isResponsePartial
          null, // responseHeaders — no build-id check for initial HTML
          initialTree,
          initialRenderedSearch,
          segmentCacheMap // hydration writes are bound to the shared map
        )
      })
      .catch(() => {
        // The static stage processing failed. Not fatal — the page
        // rendered normally, we just won't write into the cache.
      })
  } else {
    // Fully static page — cache the initial payload's segment data as-is.
    // We're not using the initial response here (which would allow us to
    // combine the two branches) to avoid unnecessary decoding of the
    // Flight data, since we can just take the segment data that we
    // already decoded during hydration and write it into the
    // cache directly.
    spawnStaticStageCacheWrite(
      Date.now(),
      // The transport subset of the initial payload, already decoded
      // during hydration. `u` (the runtime-data verdict) is deliberately
      // omitted from this synthesized subset — its writes record their
      // strategy unrefined — while the truncated branch above forwards
      // the decoded payload's own `u`.
      {
        t: initialTransportData,
        r: initialRootVaryParams,
        s: initialStaleTime,
      },
      false, // isResponsePartial
      null, // responseHeaders — no build-id check for initial HTML
      initialTree,
      initialRenderedSearch,
      segmentCacheMap // hydration writes are bound to the shared map
    )
 
    // Cancel the stream clone — fully static path doesn't need it.
    initialFlightStreamForCache?.cancel()
  }
} else {
  // No caching — cancel the unused stream clone.
  initialFlightStreamForCache?.cancel()
}
 

Copyexport function navigateReducer(
  state: ReadonlyReducerState,
  action: NavigateAction
): ReducerState {
  const { url, isExternalUrl, navigateType, scrollBehavior } = action
 
  if (isExternalUrl) {
    return completeHardNavigation(state, url, navigateType)
  }
 
  // Handles case where `<meta http-equiv="refresh">` tag is present,
  // which will trigger an MPA navigation.
  if (document.getElementById('__next-page-redirect')) {
    return completeHardNavigation(state, url, navigateType)
  }
 

Copy  // Temporary glue code between the router reducer and the new navigation
  // implementation. Eventually we'll rewrite the router reducer to a
  // state machine.
  const currentUrl = new URL(state.canonicalUrl, location.origin)
  const currentRenderedSearch = state.renderedSearch
  return navigateUsingSegmentCache(
    state,
    url,
    currentUrl,
    currentRenderedSearch,
    state.root,
    state.tree,
    state.nextUrl,
    FreshnessPolicy.Default,
    scrollBehavior,
    navigateType
  )
}

Copyexport const DYNAMIC_STALETIME_MS =
  Number(process.env.__NEXT_CLIENT_ROUTER_DYNAMIC_STALETIME) * 1000
 
export const STATIC_STALETIME_MS = getStaleTimeMs(
  Number(process.env.__NEXT_CLIENT_ROUTER_STATIC_STALETIME)
)

Copyif (process.env.__NEXT_EXPOSE_TESTING_API) {
  const { isNavigationLocked } =
    require('./segment-cache/navigation-testing-lock') as typeof import('./segment-cache/navigation-testing-lock')
  if (isNavigationLocked()) {
    // Signal that a new locked navigation is starting. This force-resolves the
    // previous locked navigation's withheld data (so a reused shared segment
    // no longer carries a pending deferred rsc) and returns this navigation's
    // own withheld-data gate.
    navigationLock = beginLockedNavigation()
    return ensurePrefetchThenNavigate(
      state,
      url,
      currentUrl,
      currentRenderedSearch,
      currentRoot,
      currentFlightRouterState,
      nextUrl,
      freshnessPolicy,
      scrollBehavior,
      navigateType,
      navigationLock
    )
  }
}

Copyfunction navigateImpl(
  state: AppRouterState,
  url: URL,
  currentUrl: URL,
  currentRenderedSearch: string,
  currentRoot: RootRouteTree<CacheNode>,
  currentFlightRouterState: FlightRouterState,
  nextUrl: string | null,
  freshnessPolicy: FreshnessPolicy,
  scrollBehavior: ScrollBehavior,
  navigateType: 'push' | 'replace',
  navigationLock: NavigationLock | null,
  // The segment cache map this navigation is bound to: a locked navigation's
  // driving-task map, or the shared map. See `segmentCacheMap` in cache.ts.
  map: CacheMap<SegmentCacheEntry>
): AppRouterState | Promise<AppRouterState> {
  const now = Date.now()
  const href = url.href
 
  const cacheKey = createCacheKey(href, nextUrl)
  const route = readRouteCacheEntry(now, cacheKey)
  if (route !== null && route.status === EntryStatus.Fulfilled) {
    // We have a matching prefetch.
    return navigateUsingPrefetchedRouteTree(
      now,
      state,
      url,
      currentUrl,
      currentRenderedSearch,
      nextUrl,
      currentRoot,
      freshnessPolicy,
      scrollBehavior,
      navigateType,
      route,
      navigationLock,
      map
    )
  }
 
  // There was no matching route tree in the cache. Let's see if we can
  // 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
  // the entry has a rejected status, since it may have been rejected due to a
  // rewrite or redirect based on the search params.
  //
  // TODO: There are multiple reasons a prefetch might be rejected; we should
  // track them explicitly and choose what to do here based on that.
  if (!process.env.__NEXT_OPTIMISTIC_ROUTING) {
    if (route === null || route.status !== EntryStatus.Rejected) {
      const optimisticRoute = deprecated_requestOptimisticRouteCacheEntry(
        now,
        url,
        nextUrl
      )
      if (optimisticRoute !== null) {

Copyexport function completeSoftNavigation(
  oldState: AppRouterState,
  url: URL,
  referringNextUrl: string | null,
  navigation: RootNavigationTask,
  renderedSearch: string,
  canonicalUrl: string,
  navigateType: 'push' | 'replace',
  scrollBehavior: ScrollBehavior,
  scrollRef: ScrollRef | null,
  collectedDebugInfo: Array<unknown> | null
) {
  // The "Next-Url" is a special representation of the URL that Next.js
  // uses to implement interception routes.
  // TODO: Get rid of this extra traversal by computing this during the
  // same traversal that computes the tree itself. We should also figure out
  // what is the minimum information needed for the server to correctly
  // intercept the route.
  const tree = navigation.tree.route
  const changedPath = computeChangedPath(oldState.tree, tree)
  const nextUrlForNewRoute = changedPath ? changedPath : oldState.nextUrl
 
  // This value is stored on the state as `previousNextUrl`; the naming is
  // confusing. What it represents is the "Next-Url" header that was used to
  // fetch the incoming route. It's essentially the refererer URL, but in a
  // Next.js specific format. During refreshes, this is sent back to the server
  // instead of the current route's "Next-Url" so that the same interception
  // logic is applied as during the original navigation.
  const previousNextUrl = referringNextUrl
 

Copyexport function refreshReducer(
  state: ReadonlyReducerState,
  action: RefreshAction
): ReducerState {
  // During a refresh, we invalidate the segment cache but not the route cache.
  // The route cache contains the tree structure (which segments exist at a
  // given URL) which doesn't change during a refresh. The segment cache
  // contains the actual RSC data which needs to be re-fetched.
  //
  // The Instant Navigation Testing API can bypass cache invalidation to
  // preserve prefetched data when refreshing after an MPA navigation. This is
  // only used for testing and is not exposed in production builds by default.
  const bypassCacheInvalidation =
    process.env.__NEXT_EXPOSE_TESTING_API && action.bypassCacheInvalidation
  if (!bypassCacheInvalidation) {
    const currentNextUrl = state.nextUrl
    const currentRoot = state.root
    invalidateSegmentCacheEntries(currentNextUrl, currentRoot)
  }
  // A full refresh has no HMR generation to cancel.
  return refreshDynamicData(state, FreshnessPolicy.RefreshAll, undefined)
}

Copyexport function refreshDynamicData(
  state: ReadonlyReducerState,
  freshnessPolicy: FreshnessPolicy.RefreshAll | FreshnessPolicy.HMRRefresh,
  signal: AbortSignal | undefined
): ReducerState {
  // During a refresh, invalidate the BFCache, which may contain dynamic data.
  invalidateBfCache()
 
  const currentNextUrl = state.nextUrl
 
  // We always send the last next-url, not the current when performing a dynamic
  // request. This is because we update the next-url after a navigation, but we
  // want the same interception route to be matched that used the last next-url.
  const nextUrlForRefresh = hasInterceptionRouteInCurrentTree(state.tree)
    ? state.previousNextUrl || currentNextUrl
    : null
 
  // A refresh is modeled as a navigation to the current URL, but where any
  // existing dynamic data (including in shared layouts) is re-fetched.
  const currentCanonicalUrl = state.canonicalUrl
  const currentUrl = new URL(currentCanonicalUrl, location.origin)
  const currentRenderedSearch = state.renderedSearch
  const currentFlightRouterState = state.tree
  const scrollBehavior = ScrollBehavior.NoScroll
  const navigationLock = getCurrentNavigationLock()
 
  // Create a NavigationSeed from the current FlightRouterState.
  // TODO: Eventually we will store this type directly on the state object
  // instead of reconstructing it on demand. Part of a larger series of
  // refactors to unify the various tree types that the client deals with.
  const now = Date.now()
  // TODO: Store the dynamic stale time on the top-level state so it's known
  // during restores and refreshes.
  const refreshSeed = createNavigationSeed(
    now,
    currentFlightRouterState,
    // No transport data (and so no vary params, no partiality, and no
    // pathname to parse params from) — this converts the base tree alone.
    null,
    null,
    true,
    null,
    currentRenderedSearch,
    null,
    UnknownDynamicStaleTime
  )
 
  // If the previous navigation hasn't pushed its history entry yet (React
  // hasn't committed its state), this refresh may commit in its place, so it
  // takes over the push. If the navigation does commit first, HistoryUpdater
  // sees that the URL already matches and replaces instead.
  const navigateType = state.pushRef.pendingPush ? 'push' : 'replace'
  return navigateToKnownRoute(
    now,
    state,
    currentUrl,
    currentCanonicalUrl,
    refreshSeed,
    currentUrl,
    currentRenderedSearch,
    state.root,
    freshnessPolicy,
    nextUrlForRefresh,
    scrollBehavior,
    navigateType,
    navigationLock,
    // A refresh is bound to the shared map.
    segmentCacheMap,
    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,
    signal
  )

Copyexport function hmrRefreshReducer(
  state: ReadonlyReducerState,
  action: HmrRefreshAction
): ReducerState {
  // HMR actions may wait behind a Server Action in the router queue. If a newer
  // generation superseded this one before it started, don't install a refresh
  // tree whose request is already canceled.
  if (action.signal?.aborted) {
    return state
  }
 
  return refreshDynamicData(state, FreshnessPolicy.HMRRefresh, action.signal)
}

Copyexport function restoreReducer(
  state: ReadonlyReducerState,
  action: RestoreAction
): ReducerState {
  // This action is used to restore the router state from the history state.
  // However, it's possible that the history state no longer contains the `FlightRouterState`.
  // We will copy over the internal state on pushState/replaceState events, but if a history entry
  // occurred before hydration, or if the user navigated to a hash using a regular anchor link,
  // the history state will not contain the `FlightRouterState`.
  // In this case, we'll continue to use the existing tree so the router doesn't get into an invalid state.
  let treeToRestore: FlightRouterState | undefined
  let renderedSearch: string | undefined
  const historyState = action.historyState
  if (historyState) {
    treeToRestore = historyState.tree
    renderedSearch = historyState.renderedSearch
  } else {
    treeToRestore = state.tree
    renderedSearch = state.renderedSearch
  }

Copyconst restoreSeed = createNavigationSeed(
  now,
  treeToRestore,
  // No transport data (and so no vary params, no partiality, and no
  // pathname to parse params from) — this converts the base tree alone.
  null,
  null,
  true,
  null,
  renderedSearch,
  null,
  UnknownDynamicStaleTime
)
const navigation = startPPRNavigation(
  now,
  currentUrl,
  state.renderedSearch,
  state.root,
  restoreSeed.root,
  FreshnessPolicy.HistoryTraversal,
  restoreSeed.dynamicStaleAt,
  false,
  accumulation,
  // A history-traversal restore is bound to the shared map.
  segmentCacheMap,
  // A history-traversal restore never restricts to the shell.
  false
)

CopyspawnDynamicRequests(
  navigation,
  restoredUrl,
  restoredNextUrl,
  FreshnessPolicy.HistoryTraversal,
  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,
  // History traversal always uses 'replace'.
  'replace',
  // Instant Navigation Testing API: a traversal is not a capture. Spawn its
  // dynamic requests ungated (null lock) so they render from cache or fetch
  // normally rather than being withheld behind the lock.
  null,
  // A history-traversal restore is bound to the shared map.
  segmentCacheMap,
  // Not an HMR refresh, so there's no request generation to cancel.
  undefined
)
// Instant Navigation Testing API: a traversal resets the lock to a fresh
// pending scope — releasing any data withheld by prior forward navigations and
// returning the panel to "awaiting" — without ending the testing session.
// No-op when the testing API is disabled or no lock is held.
resetNavigationLockToPending()
return completeTraverseNavigation(
  state,
  restoredUrl,
  renderedSearch,
  navigation,
  restoredNextUrl
)

Copyconst retryMpa = action.mpa
const retryUrl = new URL(action.url, location.origin)
const retrySeed = action.seed
const navigateType = action.navigateType
if (retryMpa || retrySeed === null) {
  // If the server did not send back data during the mismatch, fall back to
  // an MPA navigation.
  return completeHardNavigation(state, retryUrl, navigateType)
}

Copyconst headers: RequestHeaders = {
  // Enable flight response
  [RSC_HEADER]: '1',
  // Provide the current router state
  [NEXT_ROUTER_STATE_TREE_HEADER]: prepareFlightRouterStateForRequest(
    flightRouterState,
    options.isHmrRefresh
  ),
}
 
if (process.env.NODE_ENV === 'development' && options.isHmrRefresh) {
  headers[NEXT_HMR_REFRESH_HEADER] = '1'
}
 
if (nextUrl) {
  headers[NEXT_URL] = nextUrl
}