Repository navigation
Support pre-response fallbacks from cached routes #98656
cooperhotplate
started this conversation in
Ideas
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
Goals
Allow a cached route to conditionally run request-specific logic before the HTTP response begins streaming.
This would support routes with two distinct paths:
The common path should retain the benefits of Cache Components. The exceptional path should be able to access APIs such as
searchParams,cookies(), orheaders()without allowing request-specific output to enter the shared cache.Importantly, Next.js should wait for this fallback to finish before committing the response so it can still return the correct HTTP status.
Non-Goals
No response
Background
Cache Components work best when output depends only on shared application data. Request-specific APIs cannot safely be accessed inside a shared
'use cache'boundary because their values may differ between requests.That restriction makes sense. For example, caching a redirect containing one request’s query parameters could cause another request to receive the wrong destination.
However, some routes only need request-specific information after cached application data identifies an exceptional condition.
Consider a user page:
The application wants to:
aliceis an active username./alice-new?ref=instagramifaliceis a previous username.404if the username has never existed.The active path does not depend on the request’s query parameters. Only the historical-username branch needs
searchParamsso it can preserve them in the redirect.Moving that branch into an uncached child allows it to access request data, but the cached shell may already have started streaming as
200before the redirect is discovered. At that point, Next.js can perform a client-side redirect, but it may be too late to return a real HTTP307.Making the entire route dynamic avoids early streaming, but it also gives up the cached or static success path for every request—even though the request-specific behavior is only needed for an exceptional result.
Proposal
Provide an explicit pre-response fallback that can be selected by cached application data.
Conceptually:
The exact API could take a different form. The important behavior is:
404, or other routing response.This would not weaken the existing
'use cache'contract. The cached portion would still produce only deterministic, shareable results. The framework would simply provide a way for one of those results to hand control to a request-specific phase before streaming begins.This pattern is useful beyond renamed user pages. It could also apply to canonical URL resolution, migrated tenant slugs, deleted-resource replacements, locale selection, preview routing, and other cases where cached data identifies an uncommon request-specific outcome.
Perhaps
instant = falsealready provides the necessary response timing. If so, clearer guidance on composing it with nested Cache Components would be helpful. Otherwise, this seems like a missing bridge between shared cached rendering and request-specific routing.All reactions