Unverified Commit 35d91fca authored by Josh Story's avatar Josh Story Committed by GitHub

Model prerenders as render candidates (#97431)

## Summary

This is the behavior-preserving base of a four-PR stack that introduces
explicit prerender matching policy without coupling the foundational
refactor to the proposed API.

The build currently uses `PrerenderedRoute` values for two related but
distinct concepts:

- a logical request matcher that says which parameterized URL shapes the
route can handle
- a build-time render candidate that may or may not become a persisted
prerender artifact

A candidate is not guaranteed to be an output. It can be rendered only
to validate a shell, discarded, and still leave behind a matcher that
tells future requests to block.

The new relationship is:

```text
logical pathname matcher
  -> zero or more render candidates
    -> zero or more persisted artifacts
```

## Concrete example

Consider `/[top]/items/[bottom]`:

```ts
export function generateStaticParams() {
  return [{ top: 't1', bottom: 'b1' }]
}
```

Static-path generation may consider three shapes:

| Shape | Purpose |
| --- | --- |
| `/[top]/items/[bottom]` | A generic shell candidate and logical
matcher |
| `/t1/items/[bottom]` | A shell after resolving `top` |
| `/t1/items/b1` | A concrete build-time prerender |

Suppose the generic candidate renders an allowed empty shell. The build
should discard that candidate artifact and use blocking behavior for the
generic matcher. It should not remove `/[top]/items/[bottom]` from the
valid matcher set, and it should not discard the concrete `/t1/items/b1`
artifact.

This is why the build needs two sets:

- route matchers, which describe valid request shapes
- prerender candidates, whose render results determine whether an
artifact is retained and can refine inferred fallback behavior

## Variants compatibility

Variants will make pathname-only candidate maps insufficient. Several
variant combinations can share `/t1/items/b1` as their logical pathname
while writing distinct artifacts under variant-specific output paths.

This PR keeps the route matcher keyed by logical pathname but retains
every candidate associated with it. Candidate finalization can therefore
evaluate each variant artifact independently without changing the route
tree's matcher set.

## Behavior preservation

This PR does not add a user-facing API or change `generateStaticParams`
semantics:

- a usable static shell remains a fallback prerender
- an allowed empty shell is discarded and represented by a blocking
matcher
- a route that requires a non-empty shell still fails validation
- unresolved matchers remain gated by route-level PPR support
- the most-specific shell continues to supply first-writer-wins metadata
such as prefetch hints

Render results can decide whether a candidate artifact is published and
can refine inferred matcher behavior, but they do not remove the logical
route matcher itself.

## Stack plan

1. **#97431 — model prerenders as render candidates:** land the
behavior-preserving matcher/candidate separation and post-render
finalization first.
2. **#97393 — add the experimental matcher API:** add `unstable_matcher`
and `unstable_generateMatcher`, policy aggregation, validation, and
local diagnostics.
3. **#97426 — test complex route shapes:** add test-only coverage for
catch-alls, optional catch-alls, root parameters, and parallel slots.
4. **#97427 — test foreground policy behavior:** add test-only coverage
showing blocking misses generate before responding while fallback misses
return the shared shell immediately.

This layering lets the internal model be reviewed and landed
independently of the API design. The upper test PRs validate the final
behavior without increasing the implementation diff.

## Verification

- `pnpm --filter=next types`
- `pnpm test-start-turbo
test/e2e/app-dir/sub-shell-generation/sub-shell-generation.test.ts`
- `pnpm test-start-turbo
test/e2e/app-dir/segment-cache/prefetch-inlining/prefetch-inlining.test.ts`

<!-- NEXT_JS_LLM -->
parent 9dfbc938
This diff is collapsed.
...@@ -3,6 +3,7 @@ import type { AppPageModule } from '../../server/route-modules/app-page/module' ...@@ -3,6 +3,7 @@ import type { AppPageModule } from '../../server/route-modules/app-page/module'
import type { AppSegment } from '../segment-config/app/app-segments' import type { AppSegment } from '../segment-config/app/app-segments'
import type { import type {
FallbackRouteParam, FallbackRouteParam,
PrerenderRouteMatcher,
PrerenderedRoute, PrerenderedRoute,
StaticPathsResult, StaticPathsResult,
} from './types' } from './types'
...@@ -1175,5 +1176,28 @@ export async function buildAppStaticPaths({ ...@@ -1175,5 +1176,28 @@ export async function buildAppStaticPaths({
assignStaticShellMetadata(prerenderedRoutes, prerenderablePathSegments) assignStaticShellMetadata(prerenderedRoutes, prerenderablePathSegments)
} }
return { fallbackMode, prerenderedRoutes } const prerenderRouteMatchersByPathname = new Map<
string,
PrerenderRouteMatcher
>()
if (prerenderedRoutes && isRoutePPREnabled) {
for (const prerenderCandidate of prerenderedRoutes) {
if (!prerenderCandidate.fallbackRouteParams?.length) continue
prerenderRouteMatchersByPathname.set(prerenderCandidate.pathname, {
pathname: prerenderCandidate.pathname,
fallbackRouteParams: prerenderCandidate.fallbackRouteParams,
fallbackMode: prerenderCandidate.fallbackMode,
fallbackRootParams: prerenderCandidate.fallbackRootParams,
remainingPrerenderableParams:
prerenderCandidate.remainingPrerenderableParams,
})
}
}
const prerenderRouteMatchers =
prerenderRouteMatchersByPathname.size > 0
? [...prerenderRouteMatchersByPathname.values()]
: undefined
return { fallbackMode, prerenderedRoutes, prerenderRouteMatchers }
} }
...@@ -52,9 +52,40 @@ type FallbackPrerenderedRoute = { ...@@ -52,9 +52,40 @@ type FallbackPrerenderedRoute = {
throwOnEmptyStaticShell: boolean throwOnEmptyStaticShell: boolean
} }
/**
* A route the build plans to prerender. Rendering decides whether the result
* becomes a published output: for example, an allowed empty fallback shell is
* discarded and its matcher becomes blocking instead.
*
* The historical name is retained because this type is used throughout static
* path generation, but values of this type are prerender candidates rather
* than guaranteed outputs.
*/
export type PrerenderedRoute = StaticPrerenderedRoute | FallbackPrerenderedRoute export type PrerenderedRoute = StaticPrerenderedRoute | FallbackPrerenderedRoute
/**
* Describes how a dynamic pathname is matched when no concrete build-time
* output matches it. It describes the logical route independently of any
* artifacts produced for it, and is not itself something to render.
*
* Zero or more prerender candidates may share this pathname. In particular,
* variants can produce several artifacts for one logical matcher, so consumers
* must not assume pathname identifies a single candidate or render result.
*/
export type PrerenderRouteMatcher = {
readonly pathname: string
readonly fallbackRouteParams: readonly FallbackRouteParam[]
readonly fallbackMode: FallbackMode | undefined
readonly fallbackRootParams: readonly string[]
readonly remainingPrerenderableParams?: readonly FallbackRouteParam[]
}
export type StaticPathsResult = { export type StaticPathsResult = {
fallbackMode: FallbackMode | undefined fallbackMode: FallbackMode | undefined
/** Planned renders, some of which may be discarded after rendering. */
prerenderedRoutes: PrerenderedRoute[] | undefined prerenderedRoutes: PrerenderedRoute[] | undefined
/** Logical request matchers, independent of the artifacts rendered for them. */
prerenderRouteMatchers?: PrerenderRouteMatcher[]
} }
...@@ -69,7 +69,10 @@ import { createIncrementalCache } from '../export/helpers/create-incremental-cac ...@@ -69,7 +69,10 @@ import { createIncrementalCache } from '../export/helpers/create-incremental-cac
import { collectRootParamKeys } from './segment-config/app/collect-root-param-keys' import { collectRootParamKeys } from './segment-config/app/collect-root-param-keys'
import { buildAppStaticPaths } from './static-paths/app' import { buildAppStaticPaths } from './static-paths/app'
import { buildPagesStaticPaths } from './static-paths/pages' import { buildPagesStaticPaths } from './static-paths/pages'
import type { PrerenderedRoute } from './static-paths/types' import type {
PrerenderRouteMatcher,
PrerenderedRoute,
} from './static-paths/types'
import type { CacheControl } from '../server/lib/cache-control' import type { CacheControl } from '../server/lib/cache-control'
import { formatExpire, formatRevalidate } from './output/format' import { formatExpire, formatRevalidate } from './output/format'
import type { import type {
...@@ -672,6 +675,7 @@ type PageIsStaticResult = { ...@@ -672,6 +675,7 @@ type PageIsStaticResult = {
hasServerProps?: boolean hasServerProps?: boolean
hasStaticProps?: boolean hasStaticProps?: boolean
prerenderedRoutes: PrerenderedRoute[] | undefined prerenderedRoutes: PrerenderedRoute[] | undefined
prerenderRouteMatchers: PrerenderRouteMatcher[] | undefined
prerenderFallbackMode: FallbackMode | undefined prerenderFallbackMode: FallbackMode | undefined
rootParamKeys: readonly string[] | undefined rootParamKeys: readonly string[] | undefined
isNextImageImported?: boolean isNextImageImported?: boolean
...@@ -742,6 +746,7 @@ export async function isPageStatic({ ...@@ -742,6 +746,7 @@ export async function isPageStatic({
isRoutePPREnabled: false, isRoutePPREnabled: false,
prerenderFallbackMode: undefined, prerenderFallbackMode: undefined,
prerenderedRoutes: undefined, prerenderedRoutes: undefined,
prerenderRouteMatchers: undefined,
rootParamKeys: undefined, rootParamKeys: undefined,
hasStaticProps: false, hasStaticProps: false,
hasServerProps: false, hasServerProps: false,
...@@ -768,6 +773,7 @@ export async function isPageStatic({ ...@@ -768,6 +773,7 @@ export async function isPageStatic({
let componentsResult: LoadComponentsReturnType let componentsResult: LoadComponentsReturnType
let prerenderedRoutes: PrerenderedRoute[] | undefined let prerenderedRoutes: PrerenderedRoute[] | undefined
let prerenderRouteMatchers: PrerenderRouteMatcher[] | undefined
let prerenderFallbackMode: FallbackMode | undefined let prerenderFallbackMode: FallbackMode | undefined
let appConfig: AppSegmentConfig = {} let appConfig: AppSegmentConfig = {}
let rootParamKeys: readonly string[] | undefined let rootParamKeys: readonly string[] | undefined
...@@ -887,8 +893,11 @@ export async function isPageStatic({ ...@@ -887,8 +893,11 @@ export async function isPageStatic({
;({ prerenderedRoutes, fallbackMode: prerenderFallbackMode } = ;({ prerenderedRoutes, fallbackMode: prerenderFallbackMode } =
buildStaticMetadataStaticPaths(page)) buildStaticMetadataStaticPaths(page))
} else { } else {
;({ prerenderedRoutes, fallbackMode: prerenderFallbackMode } = ;({
await buildAppStaticPaths({ prerenderedRoutes,
prerenderRouteMatchers,
fallbackMode: prerenderFallbackMode,
} = await buildAppStaticPaths({
dir, dir,
page, page,
route, route,
...@@ -982,6 +991,7 @@ export async function isPageStatic({ ...@@ -982,6 +991,7 @@ export async function isPageStatic({
isRoutePPREnabled, isRoutePPREnabled,
prerenderFallbackMode, prerenderFallbackMode,
prerenderedRoutes, prerenderedRoutes,
prerenderRouteMatchers,
rootParamKeys, rootParamKeys,
hasStaticProps, hasStaticProps,
hasServerProps, hasServerProps,
......
export default async function Page({
params,
}: {
params: Promise<{ top: string; bottom: string }>
}) {
const { top, bottom } = await params
return <p>{`Dynamic page: ${top}/${bottom}`}</p>
}
import { Suspense, type ReactNode } from 'react'
import { NoInline } from '../../../components/no-inline'
export function generateStaticParams() {
return [{ top: 't1' }]
}
export default async function Layout({
children,
params,
}: {
children: ReactNode
params: Promise<{ top: string }>
}) {
const { top } = await params
return (
<div>
<NoInline />
<p>{`Top: ${top}`}</p>
<Suspense fallback={<p>Loading bottom...</p>}>{children}</Suspense>
</div>
)
}
import type { ReactNode } from 'react'
export default function Layout({ children }: { children: ReactNode }) {
return (
<div>
<p>Static parent</p>
{children}
</div>
)
}
...@@ -185,7 +185,7 @@ async function getRouteTreeFromHistory( ...@@ -185,7 +185,7 @@ async function getRouteTreeFromHistory(
} }
describe('prefetch inlining', () => { describe('prefetch inlining', () => {
const { next, isNextDev, isTurbopack } = nextTestSetup({ const { next, isNextDev, isNextStart, isTurbopack } = nextTestSetup({
files: __dirname, files: __dirname,
}) })
...@@ -533,6 +533,40 @@ describe('prefetch inlining', () => { ...@@ -533,6 +533,40 @@ describe('prefetch inlining', () => {
) )
}) })
if (isNextStart) {
it('partially generated dynamic route: build hints use the most specific shell', async () => {
const hints = await next.readJSON('.next/server/prefetch-hints.json')
expect(hints['/test-dynamic-partial/[top]/[bottom]'])
.toMatchInlineSnapshot(`
{
"hints": 64,
"slots": {
"children": {
"hints": 96,
"slots": {
"children": {
"hints": 32,
"slots": {
"children": {
"hints": 64,
"slots": {
"children": {
"hints": 160,
"slots": null,
},
},
},
},
},
},
},
},
}
`)
})
}
// TODO: Add a test for stale hints (InliningHintsStale). The stale hints // TODO: Add a test for stale hints (InliningHintsStale). The stale hints
// mechanism expires the route cache entry so the next prefetch re-fetches // mechanism expires the route cache entry so the next prefetch re-fetches
// the correct tree. This is hard to test reliably with act() because the // the correct tree. This is hard to test reliably with act() because the
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment