router.prerender() for every route: warm runtime caches before traffic, shared stores only (design) #1062

Design issue, not built. Decided on 2026-10-04: no separate router.warm(). router.prerender() stays the one verb for "make this URL ready before traffic", and dispatches by route. #640 ships it for Prerender(..., { onDemand }) routes; a PR stacked on #640, released in the same version, widens it to every route whose cache store is shared beyond the place the call runs.

Problem

After #640, router.prerender() renders a Prerender route with no request and writes it to the prerender store. Every other cache the router has fills only from a real visitor's request:

• a ppr route's shell (captured on the first document MISS);
• a route's cache() entries and the document cache;
• "use cache" entries reached by the render;
• a clientUrls() group with ppr (feat(client-urls): ppr as a projected group path option — shell caching for group routes #817). A clientUrls() group cannot use Prerender() at all (fix(client-urls): reject Static()/Prerender() handler values with a targeted message #818).

So after a deploy every key starts cold (per-app cache versions, #1034, retire the old entries of an app whose code changed), and the same after an updateTag(). The first visitor per key and partition pays the render.

API (shared with #640)

const prerender = router.prerender({ env, ctx });
await prerender("/products/1");                       // any route
await prerender.many(urls, { concurrency: 4 });       // default concurrency 1
await prerender.markStale(["product:1"]);             // the prerender store only

Dispatch

The per-target result says which path ran and what it filled or refused (PrerenderResult, extended).

Which stores are shared

Warming a cache that lives only in the colo, region or process where the call runs does nothing for traffic elsewhere.

Mechanism: an optional declaration on SegmentCacheStore, for example scope: "global" | "regional" | "local", set by the shipped stores (CFCacheStore from whether it has KV; VercelCacheStore declares itself shared per the decision above; the memory store "local"). No new knob for app authors on the shipped stores. This is a change to the store contract custom stores implement and gets its own review.

Decided

• One verb, router.prerender(), dispatched by route (not a separate router.warm()).
• Bound runner, .many() with per-call concurrency (default 1); a large list belongs in a queue, one message per batch, because one invocation runs under the platform's time and CPU limits.
• A warm replaces the URL's entries by forcing misses and overwriting in place; it needs no tags.
• Vercel: allowed for single-region deployments, documented, not detected.
• Built design-first in the stacked PR: a short write-up and red tests for the forced-miss mode, reviewed before the build (it reaches core paths every app runs through: src/cache/cache-scope.ts, src/cache/cache-runtime.ts, src/rsc/shell-capture.ts, the document cache).

Open questions

1. The synthetic request. A cookie-free GET of the full URL (host and search params included, so it lands in the same partitions as a visitor; cache.searchParams applies). What headers, if any. A route that reads cookies() or headers is already refused by the existing guards (a PPR capture refuses identity reads; a cache() fill that reads cookies stores nothing): report those, do not work around them.
2. Which caches. The document shell and the route's cache() / document-cache entries. Navigation (partial) payloads depend on the page a visitor comes from and cannot be enumerated: leave them to the first navigation, or warm the navigation shell only.
3. A Prerender route's loaders. Whether one call both refreshes the prerender store and warms the loaders' runtime caches, and in which order.
4. Result statuses. skipped-not-on-demand (from feat(router): on-demand (ISR-style) prerender #640) becomes the warm path; new statuses for a refused non-shared store and per-cache outcomes.
5. Testing. A userland test through serveShellRequest (and dispatch where it applies), as the repo requires for consumer-touchable features.

Possible follow-up, not part of this: invalidating a URL without rendering it

Like Next.js revalidatePath. If built, follow Next.js's read-side design rather than stamping path tags on entries: Next.js derives implicit tags from the path at read time and compares them with the entry's timestamp ("the implicit tags' expirations are stored in the work unit store, and used to compare with a cache entry's timestamp", packages/next/src/server/lib/implicit-tags.ts). Stamping tags on entries would miss shared entries (a layout entry written while rendering /a never gets /b's tag), add a KV marker read per tag on every hit, and count against Vercel's 128-tag limit.

Prior art

Next.js App Router regenerates only on a request: "A revalidation is triggered by a request, not by the revalidateTag call", and "We're working on adding new methods to provide eager regeneration capabilities for the App Router" (nextjs.org/docs/app/guides/incremental-static-regeneration, quoted in the #640 API review).

Related: #640 (on-demand prerender), #1060 (its follow-ups, including a Vercel prerender store), #1034 (per-app cache versions), #1043.