6 Commits

Author	SHA1	Message	Date
Hendrik Liebau	529ddc3c8d	[test] Unflake two cache-components-dev-streaming assertions (#97246) ... The streaming assertion in `should stream suspense boundaries while filling caches in the background` polled a bare `<p>` through `retry()` with its 3000ms default. Because `retry` gives up as soon as `waited + interval > duration`, the effective budget is about 2.6s, and the fixture's cache fill alone takes 2000ms, so the assertion had roughly 600ms of headroom. That budget also had to absorb one browser round trip per attempt, because a selector that matches the fallback as well as the content cannot wait for anything: `waitForSelector` returns the fallback immediately, so the waiting had to happen in the test process at a 500ms granularity. This change gives the two paragraphs the ids `#cached-fallback` and `#cached`, in line with every other route in this fixture, which is what lets the wait move into the browser. Playwright now resolves the moment the content is revealed, in a single round trip, and #95466 had already moved the rest of the suite to that pattern. The two assertions that check what the shell itself delivers still need the original "whichever element arrives first" probe, and they now express it as the selector list `#cached, #cached-fallback` instead of relying on `p` to match both. The budget for the reveal is 10s rather than the 5s that `elementByCss` narrows the harness default to, because the wait has to cover more than the fill. In the linked failure the content bytes had arrived one second after the shell committed, and the reveal was still at least 2.4s away, since the browser was busy evaluating the dev bundle. A shorter fill would not help with that, as it does not shorten the part of the wait that CI actually spends. The convergence assertion in `serves a short-expire cache warm on reload and converges to a fresh value` ran out of the same budget for a different reason: every attempt performed a full dev page reload on top of the 1.5s regeneration, and measured runs needed 1.8s to 3.4s. It now reads the value over HTTP with `next.render$`, the way #97187 does, which observes the same server-side cache state without downloading and evaluating the dev bundle. Under the same contention those reads converge in 1.1s to 1.9s, and they stay there when the load is quadrupled, because only the 1.5s regeneration gates the loop. The default budget therefore covers it, and the test drops from 15.5s to 3.6s. Both fixes were verified by raising the fill to 3.2s to emulate the CI-side delay: the previous assertions then fail deterministically with the CI signature, and the new ones pass. [Flakiness metrics](https://app.datadoghq.com/ci/test/runs?query=test_level%3Atest%20%40git.repository.id%3A%22github.com%2Fvercel%2Fnext.js%22%20%40test.name%3A%22cache-components-dev-streaming%20should%20stream%20suspense%20boundaries%20while%20filling%20caches%20in%20the%20background%22%20%40test.type%3A%22nextjs%22%20%40test.status%3A%22fail%22&agg_m=count&agg_m_source=base&agg_t=count&citest_explorer_sort=timestamp%2Casc&cols=%40test.status%2Ctimestamp%2C%40test.suite%2C%40test.name%2C%40duration%2C%40test.service%2C%40git.branch&currentTab=overview&eventStack=&fromUser=true&index=citest&start=1783948256248&end=1786540256248&paused=false)	2026-08-12 21:53:40 +02:00
Andrew Clark	3de2d1a213	Unify allow-runtime with Partial Prefetching (#96106) ... Removes the "allow-runtime" prefetch config, and turns its behavior on implicitly wherever Partial Prefetching is enabled. The original motivation for "allow-runtime" was to give apps more control over server costs triggered by prefetches. Until a route explicitly opts in, prefetches would only be served from the CDN, not from the server. The problem, though, was it was very confusing to know when to add or remove this configuration. The incentive for many apps was to add it everywhere, with no clear signal for when to remove it. Our updated thinking is that Partial Prefetching itself already provides sufficient protection against runaway prefetching costs: per-link prefetches only happen on Link components that explicitly opt in with the prefetch prop. The optimizations landed earlier in this stack also make allow-runtime less necessary: on pages where all the content is statically renderable, prefetches are served from the static cache and no runtime request is ever issued; only a page that accesses non-static data is prefetched at runtime. The upshot of this decision is that runtime versus static becomes an internal optimization; the same content gets prefetched regardless of whether or how Next.js is able to optimize it.	2026-07-28 11:51:29 -04:00
Hendrik Liebau	2850659b74	Cache short-expire 'use cache' values across dev reloads (#95362) ... Development has recently gained several mechanisms that make `'use cache'` reloads fast under Cache Components: `'use cache: private'` entries are persisted in a dedicated in-memory handler, `cacheMaxMemorySize: 0` uses a real in-memory handler instead of the no-op stub, and custom handlers are fronted by a fast built-in handler through the tiered handler. One case was still missing. A value that opts into a dynamic, client-only life with an explicit short `expire` (for example `cacheLife({ expire: 0 })`, or the built-in `'seconds'` profile) was treated as a miss on every reload, for both the built-in default handler and custom handlers, so reloads re-ran the cache function and streamed slowly. The reason is that `expire` is the value's expiration bound, the longest it may still be served before it has to be treated as expired. That is its purpose in both dev and production; what differs is which threshold the built-in in-memory handler enforces. In `next dev` it serves stale entries up to `expire` to keep reloads fast, whereas in production it drops them earlier, once past `revalidate`. An `expire` of zero therefore leaves the dev handler no window in which a reload can be served from the cache, and the wrapper's serve-vs-regenerate check, which also keys on `expire`, regenerates instead. This change extends the same dev-only treatment to those values without altering their resolved cache life. The built-in default handler now retains an entry for at least `MIN_PRERENDERABLE_EXPIRE` in dev, a minimum the custom front handler inherits by being a built-in default handler, and the wrapper applies the same minimum when deciding whether to serve or regenerate. That affects the retain and serve decisions only; the entry keeps its real `expire`, so the staged dev render still resolves it at the appropriate stage rather than in the shell stage. A short-`expire` entry is also re-warmed in the background on every dynamic request render, so a reload serves the previously cached value immediately and the freshly recomputed one appears on the next reload. This is the same stale-while-revalidate trade-off already accepted for the private-cache and `cacheMaxMemorySize: 0` dev optimizations, which likewise favor a fast reload over serving a value these configurations would not otherwise cache at all. For custom handlers the re-warm re-executes the function and writes through to the backing. Unlike the private-cache case, we deliberately do not force a dynamic cache life here, because forcing `revalidate: 0` would leak into the cache life propagated to an enclosing `'use cache'` and trip the nested-dynamic error with the wrong message. And unlike the size-0 case, keeping the resolved life alone is not enough, because a short `expire` is exactly what makes the dev handler drop the entry, which is why the minimum retention is needed. Because the dev front handler now enforces that minimum, the tiered handler can no longer evict a stale front entry by writing `expire: 0` (the minimum would keep it alive), so `toExpiredEntry` now writes a negative `expire`, which the default handler recognizes as an eviction sentinel and reports as missing regardless of the retention minimum. This mirrors the existing `revalidate = -1` convention, though a negative `expire` means the entry is dropped rather than served-but-revalidated. Everything is gated on `process.env.__NEXT_DEV_SERVER`, so production behaves exactly as before: short-`expire` values keep their real cache life, and configured handlers are used directly. New development tests cover the built-in and custom-handler cases, asserting that a cache-miss navigation shows the Suspense fallback while a cache-hit one does not, and that a reload serves the cached value yet converges to a fresh one. --- <sub>Stack created with <a href="https://github.com/github/gh-stack">GitHub Stacks CLI</a> • <a href="https://gh.io/stacks-feedback">Give Feedback 💬</a></sub>	2026-07-02 11:26:08 +02:00
Janka Uryga	8c6cb0e080	[PP] Reveal after ShellRuntime when simulating a Shell Prefetch in dev (#95149) ... When `partialPrefetching` is on, the shell that we usually care about displaying is the App Shell, which is represented by the ShellRuntime stage. We should only show the cold cache indicator for caches that happen up until then, and release the client-side promise appropriately. This PR extends the existing `revealAfterStage` mechanics to account for this. > Note that this is incomplete: if we're navigating via `<Link prefetch={true}>` (or have `partialPrefetching: "unstable_eager"), we might want to use the Runtime stage instead. I'm leaving those for a follow up -- representing the common case (a shell prefetch) seems like the most useful thing. I've re-worked the `revealAfterStage/holdStreamUntilRevealed` setup into an object (`DevNavigationKind`) that represents the navigation that we're trying to simulate -- either an initial load or a client nav. This gets rid of the invalid `holdStreamUntilRevealed = true` + `revealAfterStage = RenderStage.Runtime/ShellRuntime` combination and lets us bring the logic closer to where the stream blocking tricks actually happen. I've also done some drive-by refactoring of `streamStagedRenderInDev` to dedupe some repetitive code, because every task was basically doing the same thing. I've also moved all `revealAfter.resolve()` calls into separate tasks -- we were inconsistent about this, and the `Static` `revealAfter.resolve()` was done together with the next stage, but the `RenderStage.Runtime` was done in a separate task. --- Strangely, despite the changes working as expected for the Cold Cache indicator, I can't actually get link data (`await searchParams`) to trigger a fallback when navigating, so there's a failing test for that in `cache-components-dev-streaming.test.ts`. I'm not sure why what's causing this, but I'm leaving that investigation for a follow-up as well.	2026-06-25 14:46:17 +00:00
Hendrik Liebau	5b0aa04b10	Persist 'use cache: private' entries in dev (#94694) ... Private caches were never stored in a cache handler, so every reload in `next dev` re-ran them from scratch and they registered as a cache miss on each load. This change persists `'use cache: private'` entries in development in a dedicated built-in in-memory handler so that warm reloads are fast. The handler is gated on `process.env.__NEXT_DEV_SERVER` and is kept out of the kind-keyed handlers map so it can never be replaced by a user-configured `default` handler: private cache entries can hold data specific to the incoming request (for example, derived from its cookies or headers) and must never reach a remote or otherwise persistent handler. Production keeps private caches non-persisted as before. The coarse cache-handler key for a dev private cache is scoped by the request's cookies and headers so entries for requests with different request data don't collide. It excludes Next-internal cookies that aren't application data (the HMR refresh hash, already part of the cache key, and the instant-navigation cookie, which toggles while a navigation lock is held) and the transport and content-negotiation headers that vary between otherwise-equivalent requests (a browser reload adds `cache-control`, and `accept` and `sec-fetch-*` differ between an HTML navigation and an RSC request). Keying by only the cookies and headers a cache actually reads is left as a follow-up; read root params are already tracked that way, the same as for public caches. The cache life is forced to `revalidate: 0` with a 5-minute `expire`, so each read serves the stale entry immediately and warms a fresh one in the background through the existing stale-while-revalidate path. Cross-request deduplication now applies to private caches in development too, so concurrent requests with identical request data share a single fill; it remains skipped in production where request-specific data must not be shared across requests. To make this deterministic, `saveToCacheHandler` resolves the metadata a cross-request joiner awaits only after the entry has been written to the handler, so the joiner finds it when re-reading its recomputed key. This closes a pre-existing race in that path, present for public caches too but never surfaced by their cross-request test, where the joiner's metadata could resolve before the handler write had landed. The defensive invariant that rejected reading a private entry from a handler is removed: it only existed to narrow `cacheContext.kind` for a code path that no longer needs it, and dev now legitimately reads persisted private entries while production never registers a private handler to read from.	2026-06-11 22:30:08 +02:00
Hendrik Liebau	6f4d94ac88	Stream Cache Components dev render instead of restarting on cache miss (#94457) ... When Cache Components is enabled, `next dev` previously simulated a production loading experience on every cold request. The render did a prospective pass to detect cache misses, and on any miss it waited for every cache to fill via `cacheSignal.cacheReady()` and then restarted the render with warm caches before streaming anything, so the browser saw nothing until the slowest cache had filled. Every cold load blocked on cache population. This change replaces the restart-on-cache-miss flow with a single non-abandoning staged render that streams immediately and fills caches as a side effect. On a cold load the Suspense fallbacks stream right away and the cached content resolves as its cache fills; on a warm reload the staged progression matches the previous no-cache-miss path. The render is split into clearly owned pieces: `setUpStagedDevRender` builds the staged controller, cache signal, and resume cache; `streamStagedRenderInDev{Node,Web}` runs the streaming render and reports a result once the stream has fully finished; and `stagedRenderWithCachesInDev{Node,Web}` returns the stream and leaves the validation follow-up detached so it never blocks the response. The render advances its stages in sequential tasks, and the stream is not handed back the instant it exists: it is held until the render has advanced through the stage whose content belongs in the shell. That is the static stage for initial loads, HMR refreshes, and plain navigations, or the runtime stage for client navigations to a route with a runtime prefetch config, whose runtime-prefetchable content the navigation's prefetch would have settled. It never waits for the dynamic stage. Buffering the shell before the first flush keeps the streaming renderer from emitting a premature Suspense fallback for content that belongs in the shell, and it mirrors production, where the static shell (plus runtime-prefetchable content where configured) is served and the remaining holes stream in as fallbacks. Two internal reads that would otherwise register as synchronous IO and wrongly force the render to the dynamic stage, the cache handler's tag-expiry clock check and the hot reloader's module-scope dev client id, are now read untracked: via `performance.timeOrigin + performance.now()` like the `'use cache'` handler, and only in the browser where the HMR connection reads it, respectively. Cache Components rules validation now runs in that background follow-up, once the streamed render has fully settled. `planDevValidation` inspects the finished render and picks one of three paths: forward an invalid dynamic usage error the streamed render already recorded and stop (for example a request API used inside `'use cache'`); validate the streamed render's own chunks when it neither missed caches nor hit sync IO; or, when it did either, validate a dedicated warm-cache render instead. Because that warm render reads the filled caches back rather than filling them, it can surface an invalid dynamic usage error the cold streamed render cannot, such as a nested dynamic `use cache` cache life that propagated to a parent with no explicit `cacheLife`; that error is forwarded and validation is skipped, just as one recorded by the streamed render is. Since cold loads no longer block on cache fills, the transient cache-status indicator that reflected that wait is no longer emitted; a follow-up will instead add an indicator that tells the user whether a render streamed with cache misses, and so wasn't representative of production.	2026-06-09 10:38:12 +00:00