Prefetching and PPR | blade47/next.js Wiki | doc0

Public

Prefetching and PPR | blade47/next.js Wiki | doc0

Function / Method	Input Parameters	Return Type	Purpose
`mountLinkInstance`	`element, href, router, fetchStrategy, prefetchEnabled, setOptimisticLinkStatus, ownerStack`	`LinkInstance`	Registers a link element, coerces its URL, and initiates viewport visibility observation if enabled.
`mountFormInstance`	`element, href, router, fetchStrategy`	`void`	Registers a form element for prefetch observation based on its action URL.
`onLinkVisibilityChanged`	`element, isVisible`	`void`	Updates link visibility state, manages visible tracking sets, and triggers default priority rescheduling.
`onNavigationIntent`	`element, unstable_upgradeToDynamicPrefetch`	`void`	Handles hover or touch interactions, optionally upgrading fetch strategy and rescheduling with intent priority.
`pingVisibleLinks`	`nextUrl, tree`	`void`	Iterates over visible links, checks for dirty cache states, cancels stale tasks, and reschedules work.
`prefetch`	`href, nextUrl, treeAtTimeOfPrefetch, fetchStrategy, onInvalidate`	`void`	Validates an imperative prefetch URL and schedules a prefetch task with default priority and invalidation callback.

Entry Status / Parameter	Source Value / Constant	Meaning / Handling
`EntryStatus.Empty`	Uninitialized / Cache miss	No request in progress; spawns a fetch task and upgrades state.
`EntryStatus.Pending`	In-progress request	A fetch is underway; subsequent tasks attach to `blockedTasks`.
`EntryStatus.Fulfilled`	Complete cache record	Contains valid RSC data, `staleAt` timestamp, and `isPartial` flag.
`EntryStatus.Rejected`	Failed load / 404	Request failed or was rejected inside a loading boundary.
`STATIC_STALETIME_MS`	Fallback duration	Default staleness window applied when no server header or iterable is present.

Dynamic Parameter Type	Source Identifier	Runtime Matching Behavior
Regular Dynamic	`'d'`	Consumes exactly 1 URL part and recurses deeper to find leaf patterns.
Required Catch-All	`'c'`	Consumes 1 or more remaining URL parts (`pathnameParts.slice(partIndex)`).
Optional Catch-All	`'oc'`	Consumes 0 or more URL parts; defaults to an empty array when `urlPart` is null.
Intercepted Routes	`'ci(...)'`, `'di(...)'`	Bails out to server resolution because behavior depends on navigation referrer context.

Design Choice	Benefit	Cost
Trie-based `KnownRoutePart` storage	Fast O(path length) client-side lookups	Append-only structure with no eviction inside sessions
Pattern reification via cloning	Instantly produces valid synthetic cache entries	Allocates new tree structures on cache prediction hits
Static children priority over dynamic	Prevents static routes from capturing dynamic matches	Requires tracking static siblings during discovery

Enum / Type Name	Member / Value	Purpose & Runtime Behavior
`FreshnessPolicy`	`Default`	Standard user-initiated navigation through links or router pushes.
`FreshnessPolicy`	`Hydration`	Initial application load from server-embedded HTML seed data.
`FreshnessPolicy`	`HistoryTraversal`	Browser back/forward history navigation restoring cached states.
`FreshnessPolicy`	`RefreshAll`	Full router refresh explicitly requested by user actions or triggers.
`FreshnessPolicy`	`HMRRefresh`	Development-mode Fast Refresh updating modified modules.
`FreshnessPolicy`	`Gesture`	Pointer gesture or hover-triggered prefetch hint navigation.
`NavigationTaskStatus`	`Pending`	Task requires a dynamic server request to resolve missing holes.
`NavigationTaskStatus`	`Fulfilled`	Task is fully static or populated with available cache seed data.
`NavigationTaskStatus`	`Rejected`	Task failed or encountered a route tree mismatch.
`NavigationTaskExitStatus`	`Done`	No additional navigation actions or retries are required.
`NavigationTaskExitStatus`	`SoftRetry`	Data failed to load due to tree mismatch; retry soft navigation.
`NavigationTaskExitStatus`	`HardRetry`	Unrecoverable failure in parallel route; fall back to MPA retry.

Prerender Outcome	Detection Condition	Handling & Postponed State
`Dynamic HTML`	`accessedDynamicData()` is true AND `postponed != null`	Generates postponed state via `getDynamicHTMLPostponedState()` using `DynamicHTMLPreludeState.Empty` or `Full`.
`Dynamic Data`	`accessedDynamicData()` is true AND `postponed == null`	Generates postponed state via `getDynamicDataPostponedState()` without resuming HTML shells.
`Static`	`accessedDynamicData()` is false	Statically encodes all server-inserted HTML and Flight data without dynamic holes.

Function Name	Parameters	Return Type	Purpose
`computeDynamicStaleAt`	`now: number`, `dynamicStaleTimeSeconds: number`	`number`	Converts server-sent dynamic stale seconds into an absolute millisecond timestamp.
`invalidateBfCache`	none	`void`	Increments `currentBfCacheVersion` to invalidate stale session records.
`writeToBFCache`	`now`, `varyPath`, `rsc`, `prefetchRsc`, `head`, `prefetchHead`, `dynamicStaleAt`, `bfcacheId`	`void`	Stores a completed navigation entry in `bfcacheMap`.
`readFromBFCache`	`varyPath: SegmentVaryPath`	`BFCacheEntry \| null`	Retrieves a cached history entry bypassing timestamp checks.
`readFromBFCacheDuringRegularNavigation`	`now: number`, `varyPath: SegmentVaryPath`	`BFCacheEntry \| null`	Queries cached entries subject to normal TTL and staleness validation.

Cookie State	Raw Value Condition	Meaning
`empty`	`raw === ''`	No testing lock cookie is present.
`pending`	`parsed[2]` is neither `null` nor present as object	External actor initiated a pending navigation test scope.
`mpa`	`parsed[2] === null`	Static shell served; captured Multi-Page Application mode.
`spa`	`parsed[2]` is an object (`from` / `to` tree)	Prefetch resolved; captured Single-Page Application mode.

Constant Name	Value	Purpose
`DB_NAME`	`'__next_debug_channel'`	IndexedDB database identifier for persisted debug chunks.
`STORE_NAME`	`'channels'`	Object store holding `DebugChannelEntry` records keyed by `requestId`.
`CREATED_AT_INDEX`	`'createdAt'`	Index name used for ordered cursor traversal and pruning.
`MAX_ENTRIES`	`10`	Maximum number of debug entries retained before oldest pruning occurs.