Unverified Commit e4801332 authored by Josh Story's avatar Josh Story Committed by GitHub

Record parameter matching usage in build metadata (#99594)

## Summary

The experimental parameter matching APIs may not yet be supported by
some hosts that package Next.js builds without adapters. Add an optional
`__private_unstable_hasParamMatching: true` field to
`prerender-manifest.json` so those hosts can temporarily detect API
usage and warn about unsupported deployments rather than infer it from
generated routing behavior.

The field records evaluated layout and page exports, including
generators, empty fragments, and overridden configuration. It is omitted
when matching configuration was not evaluated and disappears when
rebuilding after the last export is removed.

This private field is temporary and will be removed; it is not a lasting
API-usage signal.

This is host-neutral metadata only: it adds no deployment restriction,
changes no runtime behavior, and does not change the public adapter
interface.

## Verification

- Production fixture passes with Turbopack and webpack: 6 cases each
covering usage, absence, and rebuild cleanup.
- An ordinary full `next build`, without route filtering, also emits the
marker.
- Type checking and formatting/lint checks pass.

<!-- NEXT_JS_LLM -->
parent 9997c1c0
...@@ -457,6 +457,11 @@ const ALLOWED_HEADERS: string[] = [ ...@@ -457,6 +457,11 @@ const ALLOWED_HEADERS: string[] = [
export type PrerenderManifest = { export type PrerenderManifest = {
version: 4 version: 4
/**
* Temporary compatibility marker for hosts without adapter support for
* parameter matching. This will be removed; it is not an API-usage signal.
*/
__private_unstable_hasParamMatching?: true
routes: { [route: string]: PrerenderManifestRoute } routes: { [route: string]: PrerenderManifestRoute }
dynamicRoutes: { [route: string]: DynamicPrerenderManifestRoute } dynamicRoutes: { [route: string]: DynamicPrerenderManifestRoute }
notFoundRoutes: string[] notFoundRoutes: string[]
...@@ -3160,6 +3165,12 @@ export default async function build( ...@@ -3160,6 +3165,12 @@ export default async function build(
const prerenderManifest: PrerenderManifest = { const prerenderManifest: PrerenderManifest = {
version: 4, version: 4,
// Record evaluated exports, including empty fragments, rather than
// inferring API usage from the resulting fallback modes.
__private_unstable_hasParamMatching:
[...paramMatchingByRoute.values()].some(
(paramMatching) => paramMatching !== undefined
) || undefined,
routes: {}, routes: {},
dynamicRoutes: {}, dynamicRoutes: {},
notFoundRoutes: [], notFoundRoutes: [],
......
export async function unstable_generateParamMatching() {
return {}
}
export default function Page() {
return <p>Empty generated matching</p>
}
export async function unstable_generateParamMatching() {
return { slug: 'fallback' } as const
}
export default function Page() {
return <p>Generated matching</p>
}
import type { ReactNode } from 'react'
export const unstable_paramMatching = { slug: 'fallback' } as const
export default function Layout({ children }: { children: ReactNode }) {
return children
}
export default function Page() {
return <p>Layout-only matching</p>
}
import type { ReactNode } from 'react'
export default function Root({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
import type { ReactNode } from 'react'
export const unstable_paramMatching = { slug: 'fallback' } as const
export default function Layout({ children }: { children: ReactNode }) {
return children
}
export const unstable_paramMatching = { slug: 'blocking' } as const
export default function Page() {
return <p>Overridden matching</p>
}
export default function Page() {
return <p>hello world</p>
}
export default function Page() {
return <p>Unconfigured matching</p>
}
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
}
export default nextConfig
import { nextTestSetup } from 'e2e-utils'
describe('param-matching-build-metadata', () => {
const { next } = nextTestSetup({
files: __dirname,
skipStart: true,
})
async function buildRoute(route: string) {
const { exitCode, cliOutput } = await next.build({
args: ['--debug-build-paths', `app/${route}/page.tsx`],
})
expect({ exitCode, cliOutput }).toEqual({
exitCode: 0,
cliOutput: expect.any(String),
})
return next.readJSON('.next/prerender-manifest.json')
}
it.each(['layout-only', 'generated', 'empty-generated', 'overridden'])(
'records parameter matching used by %s',
async (route) => {
const manifest = await buildRoute(`${route}/[slug]`)
expect(manifest.__private_unstable_hasParamMatching).toBe(true)
}
)
it('does not mark unconfigured dynamic routes', async () => {
const manifest = await buildRoute('unconfigured/[slug]')
expect(manifest).not.toHaveProperty('__private_unstable_hasParamMatching')
})
it('clears the marker when the last matching export is removed', async () => {
const route = 'layout-only/[slug]'
expect((await buildRoute(route)).__private_unstable_hasParamMatching).toBe(
true
)
await next.patchFile(
`app/${route}/layout.tsx`,
(content) =>
content.replace(
"export const unstable_paramMatching = { slug: 'fallback' } as const\n",
''
),
async () => {
const manifest = await buildRoute(route)
expect(manifest).not.toHaveProperty(
'__private_unstable_hasParamMatching'
)
}
)
})
})
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