Add unstable parameter matching APIs (#97393)
## Summary
Let Cache Components applications configure parameter matching
separately from build-time prerenders. `generateStaticParams` continues
to supply concrete examples; the new `unstable_paramMatching` and
`unstable_generateParamMatching` exports control whether a novel value
returns 404, blocks on generation, receives a fallback shell, or stays
dynamic.
With `cacheComponents: true`:
```ts
// app/[lang]/layout.tsx
export const unstable_paramMatching = { lang: 'not-found' }
// app/[lang]/catalog/[top]/items/[bottom]/page.tsx
export const unstable_paramMatching = {
top: 'blocking',
bottom: 'fallback',
}
export function generateStaticParams() {
return [{ lang: 'en', top: 't1', bottom: 'b1' }]
}
```
This prerenders `/en/catalog/t1/items/b1`. A language other than `en`
returns 404. On a cache miss, `/en/catalog/t2/items/b2` blocks on
generation, while `/en/catalog/t1/items/b2` can receive fallback UI
immediately. `dynamic` keeps a parameter out of prerenders.
Alternatively, `export async function unstable_generateParamMatching()`
returns the same partial object. It takes no arguments and runs
independently of `generateStaticParams`, once per module within each
route evaluation. Public `use cache` helpers are supported. No
additional configuration flag is required, and `ParamMatching` from
`next` provides optional strict typing.
Policies merge from layouts toward pages, with descendants overriding
only supplied keys:
- A module can configure parameters at or above its segment. Explicit
modes must follow URL order: `not-found → blocking → fallback →
dynamic`.
- A `not-found` parameter requires every preceding parameter to be
explicitly `not-found`, too. Every route or parallel branch sharing that
parameter definition must agree.
- Unconfigured parameters retain inference. An unconfigured tail without
examples stays dynamic; explicitly dynamic parameters cannot be included
in prerenders.
- Shell validation follows explicit fallback boundaries instead of
silently replacing them with blocking behavior; `instant = false` opts
out of that validation. With these APIs, `output: 'export'` requires all
parameters to be explicitly `not-found`.
- `unstable_ensureStatic = 'navigation'` allows `blocking` and
`not-found`, but rejects effective `fallback` and `dynamic` policies in
both builds and development. It still requires complete
`generateStaticParams` examples and fully static server output, even
with `instant = false`. Supporting fallbacks for fully static
navigations is deferred to a follow-up.
Runtime admission, cache regeneration, and client route discovery
preserve those boundaries. Adapter output uses the existing routing
contract, including prefixed query keys for root fallbacks.
## Verification
- Unit and integration coverage for policy merging, validation,
generated types, shell selection, blocking/fallback behavior,
navigation, parameter encoding, revalidation, and root-cache isolation.
- Real fixtures cover direct, inherited, generated, and parallel-slot
combinations with `ensureStatic`, including valid overrides, missing
examples, dynamic-data errors, and preserved closed prefixes. Both
bundlers and both Partial Prefetching settings are covered in
build/start and dev.
- Existing `ensure-static-navigation` build/dev validation and
`ensure-static-navigation-runtime` production suites pass without
changing their fixtures or validation implementation.
- Routing, generator, and root-parameter fixtures have passed real
adapter deployment tests in both ordinary and Cache Components jobs.
Local adapter-output assertions separately check the root-fallback query
contract.
- [ ] Confirm cold open-suffix requests and revalidation in a deployment
known to use grouped functions, and verify rejected prefixes do not
invoke a function or consult ISR. Passing HTTP assertions alone does not
establish these properties.
<!-- NEXT_JS_LLM -->
Showing
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
Please
register
or
sign in
to comment