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

Resolve metadata independently across parallel routes (#97345)

## Motivation

Parallel routes are separate rendering branches, but the existing
metadata resolver collects every matched slot into one shared chain. As
a result, traversal order can decide which slot supplies the document
head, and metadata errors from one slot can interfere with another.

## What this does

This adds a fork-aware resolver behind
`experimental.parallelRouteMetadata` while retaining the existing
resolver as the default. Each slot resolves metadata and viewport
independently, with isolated accumulators, and a single branch is
selected for the document head at every fork.

The built-in selector prefers real routes over implicit fallbacks and
prefers `children` when it contributes head data. Otherwise it chooses
the branch with the deepest head definition, using route depth and
lexical slot order only as stable tie-breakers.

Head selection is separate from rendering outcomes. Every slot gets its
own `MetadataOutlet`, which replays navigation and regular errors for
that slot regardless of which branch supplied the head.

## Review notes

- `generateMetadata`, `generateViewport`, and generated static metadata
still start eagerly; a fork does not serialize sibling branches or
parent/child generation.
- Branch state is isolated only where the tree forks, preventing
metadata mutation from crossing between slots.
- An outlet rejects as soon as either metadata or viewport rejects, but
resolves only after both succeed. This lets one failing result reach the
slot boundary even if the other never settles.
- Existing navigation convention metadata is preserved for the selected
branch. Errors from unselected branches remain observable only through
their own rendered outlets.
- The old resolver remains available behind an explicit flag so this
implementation can be compared or disabled during rollout.

## Verification

- `pnpm --filter=next types`
- Metadata resolver unit coverage
- Parallel-route metadata, navigation, and not-found coverage in
development and production with Turbopack and webpack

<!-- NEXT_JS_LLM -->
parent 2aaa6e81
......@@ -169,6 +169,9 @@ export function getDefineEnv({
'process.env.__NEXT_APP_NAV_FAIL_HANDLING': Boolean(
config.experimental.appNavFailHandling
),
'process.env.__NEXT_PARALLEL_ROUTE_METADATA': Boolean(
config.experimental.parallelRouteMetadata
),
'process.env.__NEXT_TURBOPACK_SHARED_RUNTIME': Boolean(
config.experimental.turbopackSharedRuntime
),
......
......@@ -937,6 +937,9 @@ export function createAppPageEntrypoint({
optimisticRouting: Boolean(
nextConfig.experimental.optimisticRouting
),
parallelRouteMetadata: Boolean(
nextConfig.experimental.parallelRouteMetadata
),
inlineCss: Boolean(nextConfig.experimental.inlineCss),
prefetchInlining:
nextConfig.experimental.prefetchInlining ?? false,
......
......@@ -170,6 +170,9 @@ async function requestHandler(
staleTimes: nextConfig.experimental.staleTimes,
dynamicOnHover: Boolean(nextConfig.experimental.dynamicOnHover),
optimisticRouting: Boolean(nextConfig.experimental.optimisticRouting),
parallelRouteMetadata: Boolean(
nextConfig.experimental.parallelRouteMetadata
),
inlineCss: Boolean(nextConfig.experimental.inlineCss),
prefetchInlining: nextConfig.experimental.prefetchInlining ?? false,
authInterrupts: Boolean(nextConfig.experimental.authInterrupts),
......
......@@ -520,6 +520,8 @@ async function exportAppImpl(
nextConfig.experimental.clientParamParsingOrigins,
dynamicOnHover: nextConfig.experimental.dynamicOnHover ?? false,
optimisticRouting: nextConfig.experimental.optimisticRouting ?? false,
parallelRouteMetadata:
nextConfig.experimental.parallelRouteMetadata ?? false,
inlineCss: nextConfig.experimental.inlineCss ?? false,
prefetchInlining: nextConfig.experimental.prefetchInlining ?? false,
authInterrupts: !!nextConfig.experimental.authInterrupts,
......
type CreateMetadataComponents =
typeof import('./metadata').createMetadataComponents
let createMetadataComponentsImpl: CreateMetadataComponents
if (process.env.__NEXT_PARALLEL_ROUTE_METADATA) {
createMetadataComponentsImpl = (
require('./metadata-parallel') as typeof import('./metadata-parallel')
).createMetadataComponents
} else {
createMetadataComponentsImpl = (
require('./metadata') as typeof import('./metadata')
).createMetadataComponents
}
export { createMetadataComponentsImpl as createMetadataComponents }
This diff is collapsed.
import React, { Suspense, cache } from 'react'
import type { ParsedUrlQuery } from 'querystring'
import type { Params } from '../../server/request/params'
import type { LoaderTree } from '../../server/lib/app-dir-module'
import type { SearchParams } from '../../server/request/search-params'
import { createServerSearchParamsForMetadata } from '../../server/request/search-params'
import { createServerPathnameForMetadata } from '../../server/request/pathname'
import type { MetadataErrorType } from './metadata-resolution-primitives'
import {
resolveMetadataForBranch,
resolveMetadataResolution,
resolveViewportForBranch,
} from './resolve-metadata-parallel'
import type { MetadataContext } from './types/resolvers'
import {
createMetadataElements,
createViewportElements,
} from './metadata-elements'
import {
MetadataBoundary,
ViewportBoundary,
OutletBoundary,
} from '../framework/boundary-components'
export function createMetadataComponents({
tree,
pathname,
parsedQuery,
metadataContext,
interpolatedParams,
errorType,
serveStreamingMetadata,
}: {
tree: LoaderTree
pathname: string
parsedQuery: SearchParams
metadataContext: MetadataContext
interpolatedParams: Params
errorType?: MetadataErrorType | 'redirect'
serveStreamingMetadata: boolean
}): {
Viewport: React.ComponentType
Metadata: React.ComponentType
MetadataOutlet: React.ComponentType<{ tree: LoaderTree }>
} {
const searchParams = createServerSearchParamsForMetadata(parsedQuery)
const pathnameForMetadata = createServerPathnameForMetadata(pathname)
async function Viewport() {
const tags = await getMetadataResolution(
tree,
pathnameForMetadata,
searchParams,
interpolatedParams,
metadataContext,
errorType
)
.then(async (resolution) => {
const selected = await resolution.selectedViewport
if (selected.status === 'resolved') {
return <>{createViewportElements(selected.value)}</>
}
if (
!errorType &&
(selected.status === 'not-found' ||
selected.status === 'forbidden' ||
selected.status === 'unauthorized')
) {
const convention = await getViewportForBranch(
tree,
pathnameForMetadata,
searchParams,
selected.status,
interpolatedParams,
metadataContext,
resolution.selectedKeyPath
)
if (convention.status === 'resolved') {
return <>{createViewportElements(convention.value)}</>
}
}
return null
})
.catch(() => {
// We're going to throw the error from the metadata outlet so we just render null here instead
return null
})
return tags
}
Viewport.displayName = 'Next.Viewport'
function ViewportWrapper() {
return (
<ViewportBoundary>
<Viewport />
</ViewportBoundary>
)
}
async function Metadata() {
const tags = await getResolvedParallelMetadata(
tree,
pathnameForMetadata,
searchParams,
interpolatedParams,
metadataContext,
errorType
).catch(() => {
// We're going to throw the error from the metadata outlet so we just render null here instead
return null
})
return tags
}
Metadata.displayName = 'Next.Metadata'
function MetadataWrapper() {
// TODO: We shouldn't change what we render based on whether we are streaming or not.
// If we aren't streaming we should just block the response until we have resolved the
// metadata.
if (!serveStreamingMetadata) {
return (
<MetadataBoundary>
<Metadata />
</MetadataBoundary>
)
}
return (
<div hidden>
<MetadataBoundary>
<Suspense name="Next.Metadata">
<Metadata />
</Suspense>
</MetadataBoundary>
</div>
)
}
function MetadataOutlet({ tree: outletTree }: { tree: LoaderTree }) {
const metadataResolution = getMetadataResolution(
tree,
pathnameForMetadata,
searchParams,
interpolatedParams,
metadataContext,
errorType
)
const pendingOutlet = metadataResolution.then(
(resolution) => resolution.outlets.get(outletTree) ?? null
)
// TODO: We shouldn't change what we render based on whether we are streaming or not.
// If we aren't streaming we should just block the response until we have resolved the
// metadata.
if (!serveStreamingMetadata) {
return <OutletBoundary>{pendingOutlet}</OutletBoundary>
}
return (
<OutletBoundary>
<Suspense name="Next.MetadataOutlet">{pendingOutlet}</Suspense>
</OutletBoundary>
)
}
MetadataOutlet.displayName = 'Next.MetadataOutlet'
return {
Viewport: ViewportWrapper,
Metadata: MetadataWrapper,
MetadataOutlet,
}
}
const getResolvedParallelMetadata = cache(getResolvedParallelMetadataImpl)
async function getResolvedParallelMetadataImpl(
tree: LoaderTree,
pathname: Promise<string>,
searchParams: Promise<ParsedUrlQuery>,
interpolatedParams: Params,
metadataContext: MetadataContext,
errorType: MetadataErrorType | 'redirect' | undefined
): Promise<React.ReactNode> {
const resolution = await getMetadataResolution(
tree,
pathname,
searchParams,
interpolatedParams,
metadataContext,
errorType
)
const selected = await resolution.selectedMetadata
if (selected.status === 'resolved') {
return <>{createMetadataElements(selected.value)}</>
}
if (
!errorType &&
(selected.status === 'not-found' ||
selected.status === 'forbidden' ||
selected.status === 'unauthorized')
) {
const convention = await getMetadataForBranch(
tree,
pathname,
searchParams,
selected.status,
interpolatedParams,
metadataContext,
resolution.selectedKeyPath
)
if (convention.status === 'resolved') {
return <>{createMetadataElements(convention.value)}</>
}
}
return null
}
const getMetadataResolution = cache(resolveMetadataResolutionImpl)
async function resolveMetadataResolutionImpl(
tree: LoaderTree,
pathname: Promise<string>,
searchParams: Promise<ParsedUrlQuery>,
interpolatedParams: Params,
metadataContext: MetadataContext,
errorType?: MetadataErrorType | 'redirect'
) {
const errorConvention = errorType === 'redirect' ? undefined : errorType
return resolveMetadataResolution(
tree,
pathname,
searchParams,
errorConvention,
interpolatedParams,
metadataContext
)
}
const getMetadataForBranch = cache(resolveMetadataForBranch)
const getViewportForBranch = cache(resolveViewportForBranch)
......@@ -50,20 +50,16 @@ import type {
export type StaticIcons = Pick<ResolvedIcons, 'icon' | 'apple'>
export type Resolved<T> = T extends Metadata
? ResolvedMetadata
: ResolvedViewport
export type InstrumentedResolver<TData> = ((
parent: Promise<Resolved<TData>>
export type InstrumentedResolver<TData, TResolved> = ((
parent: Promise<TResolved>
) => TData | Promise<TData>) & {
$$original: (
props: unknown,
parent: Promise<Resolved<TData>>
parent: Promise<TResolved>
) => TData | Promise<TData>
}
export type MetadataResolver = InstrumentedResolver<Metadata>
export type ViewportResolver = InstrumentedResolver<Viewport>
export type MetadataResolver = InstrumentedResolver<Metadata, ResolvedMetadata>
export type ViewportResolver = InstrumentedResolver<Viewport, ResolvedViewport>
export type MetadataErrorType = 'not-found' | 'forbidden' | 'unauthorized'
......@@ -227,6 +223,7 @@ export async function mergeMetadata(
metadataContext,
buildState,
leafSegmentStaticIcons,
cloneResolvedMetadata = true,
}: {
metadata: Metadata | null
resolvedMetadata: ResolvedMetadata
......@@ -235,9 +232,12 @@ export async function mergeMetadata(
metadataContext: MetadataContext
buildState: BuildState
leafSegmentStaticIcons: StaticIcons
cloneResolvedMetadata?: boolean
}
): Promise<ResolvedMetadata> {
const newResolvedMetadata = structuredClone(resolvedMetadata)
const newResolvedMetadata = cloneResolvedMetadata
? structuredClone(resolvedMetadata)
: resolvedMetadata
const metadataBase = normalizeMetadataBase(
metadata?.metadataBase !== undefined
......@@ -457,11 +457,15 @@ export async function mergeMetadata(
export function mergeViewport({
resolvedViewport,
viewport,
cloneResolvedViewport = true,
}: {
resolvedViewport: ResolvedViewport
viewport: Viewport | null
cloneResolvedViewport?: boolean
}): ResolvedViewport {
const newResolvedViewport = structuredClone(resolvedViewport)
const newResolvedViewport = cloneResolvedViewport
? structuredClone(resolvedViewport)
: resolvedViewport
if (viewport) {
for (const key_ in viewport) {
......
This diff is collapsed.
This diff is collapsed.
......@@ -35,7 +35,6 @@ import {
type MetadataErrorType,
type MetadataItems,
type PageProps,
type Resolved,
type SegmentProps,
type SelectedMetadata,
type TitleTemplates,
......@@ -390,7 +389,7 @@ function prerenderMetadata(metadataItems: MetadataItems) {
> = []
for (let i = 0; i < metadataItems.length; i++) {
const metadataExport = metadataItems[i][0]
getResult<Metadata>(resolversAndResults, metadataExport)
getResult<Metadata, ResolvedMetadata>(resolversAndResults, metadataExport)
}
return resolversAndResults
}
......@@ -404,18 +403,16 @@ function prerenderViewport(viewportItems: ViewportItems) {
> = []
for (let i = 0; i < viewportItems.length; i++) {
const viewportExport = viewportItems[i]
getResult<Viewport>(resolversAndResults, viewportExport)
getResult<Viewport, ResolvedViewport>(resolversAndResults, viewportExport)
}
return resolversAndResults
}
const noop = () => {}
function getResult<TData extends object>(
resolversAndResults: Array<
((value: Resolved<TData>) => void) | Result<TData>
>,
exportForResult: null | TData | InstrumentedResolver<TData>
function getResult<TData extends object, TResolved>(
resolversAndResults: Array<((value: TResolved) => void) | Result<TData>>,
exportForResult: null | TData | InstrumentedResolver<TData, TResolved>
) {
if (typeof exportForResult === 'function') {
// If the function is a 'use cache' function that uses the parent data as
......@@ -431,7 +428,7 @@ function getResult<TData extends object>(
exportForResult.$$original
)
if (useCacheFunctionInfo && useCacheFunctionInfo.usedArgs[1]) {
const promise = new Promise<Resolved<TData>>((resolve) =>
const promise = new Promise<TResolved>((resolve) =>
resolversAndResults.push(resolve)
)
resolversAndResults.push(
......@@ -447,9 +444,7 @@ function getResult<TData extends object>(
result = exportForResult()
} else {
result = exportForResult(
new Promise<Resolved<TData>>((resolve) =>
resolversAndResults.push(resolve)
)
new Promise<TResolved>((resolve) => resolversAndResults.push(resolve))
)
}
resolversAndResults.push(result)
......
......@@ -72,7 +72,7 @@ type CreateComponentTreeProps = {
missingSlots?: Set<string>
preloadCallbacks: PreloadCallbacks
authInterrupts: boolean
MetadataOutlet: ComponentType
MetadataOutlet: ComponentType<{ tree: LoaderTree }>
isPrerendering: boolean
hintTree: PrefetchHints | null
}
......@@ -153,7 +153,7 @@ async function createComponentTreeInternal(
missingSlots?: Set<string>
preloadCallbacks: PreloadCallbacks
authInterrupts: boolean
MetadataOutlet: ComponentType | null
MetadataOutlet: ComponentType<{ tree: LoaderTree }> | null
isPrerendering: boolean
hintTree: PrefetchHints | null
},
......@@ -630,9 +630,10 @@ async function createComponentTreeInternal(
missingSlots,
preloadCallbacks,
authInterrupts,
// `StreamingMetadataOutlet` is used to conditionally throw. In the case of parallel routes we will have more than one page
// but we only want to throw on the first one.
MetadataOutlet: isChildrenRouteKey ? MetadataOutlet : null,
MetadataOutlet:
experimental.parallelRouteMetadata || isChildrenRouteKey
? MetadataOutlet
: null,
isPrerendering,
hintTree: childHintTree,
},
......@@ -924,7 +925,7 @@ async function createComponentTreeInternal(
},
wrappedPageElement,
layerAssets,
MetadataOutlet ? createElement(MetadataOutlet, null) : null
MetadataOutlet ? createElement(MetadataOutlet, { tree }) : null
),
parallelRouteNodes,
loadingData,
......
......@@ -58,7 +58,7 @@ export {
} from '../request/params'
export * as serverHooks from '../../client/components/hooks-server-context'
export { HTTPAccessFallbackBoundary } from '../../client/components/http-access-fallback/error-boundary'
export { createMetadataComponents } from '../../lib/metadata/metadata'
export { createMetadataComponents } from '../../lib/metadata'
export { RootLayoutBoundary } from '../../lib/framework/boundary-components'
export { preloadStyle, preloadFont, preconnect } from './rsc/preloads'
......
......@@ -163,6 +163,7 @@ export interface RenderOptsPartial {
clientParamParsingOrigins: string[] | undefined
dynamicOnHover: boolean
optimisticRouting: boolean
parallelRouteMetadata: boolean
inlineCss: boolean
prefetchInlining: PrefetchInliningConfig
authInterrupts: boolean
......
......@@ -70,7 +70,7 @@ export async function walkTreeWithFlightRouterState({
rootLayoutIncluded: boolean
ctx: AppRenderContext
preloadCallbacks: PreloadCallbacks
MetadataOutlet: React.ComponentType
MetadataOutlet: React.ComponentType<{ tree: LoaderTree }>
hintTree: PrefetchHints | null
}): Promise<NavigationResponseTree | null> {
const {
......@@ -355,7 +355,7 @@ export async function createFullTreeForNavigation({
injectedFontPreloadTags: Set<string>
ctx: AppRenderContext
preloadCallbacks: PreloadCallbacks
MetadataOutlet: React.ComponentType
MetadataOutlet: React.ComponentType<{ tree: LoaderTree }>
}): Promise<NavigationResponseTree> {
const {
renderOpts: { experimental },
......
......@@ -605,6 +605,8 @@ export default abstract class Server<
dynamicOnHover: this.nextConfig.experimental.dynamicOnHover ?? false,
optimisticRouting:
this.nextConfig.experimental.optimisticRouting ?? false,
parallelRouteMetadata:
this.nextConfig.experimental.parallelRouteMetadata ?? false,
inlineCss: this.nextConfig.experimental.inlineCss ?? false,
prefetchInlining:
this.nextConfig.experimental.prefetchInlining ?? false,
......
......@@ -196,6 +196,7 @@ export const experimentalSchema = {
useSkewCookie: z.boolean().optional(),
after: z.boolean().optional(),
appNavFailHandling: z.boolean().optional(),
parallelRouteMetadata: z.boolean().optional(),
coldCacheBadge: z.boolean().optional(),
collapseAdapterRoutes: z.boolean().optional(),
preloadEntriesOnStart: z.boolean().optional(),
......
......@@ -515,6 +515,7 @@ export interface ExperimentalConfig {
cacheHandlers?: NextConfig['cacheHandlers']
multiZoneDraftMode?: boolean
appNavFailHandling?: boolean
parallelRouteMetadata?: boolean
prerenderEarlyExit?: boolean
linkNoTouchStart?: boolean
caseSensitiveRoutes?: boolean
......@@ -2283,6 +2284,7 @@ export const defaultConfig = Object.freeze({
cssChunking: true,
multiZoneDraftMode: false,
appNavFailHandling: false,
parallelRouteMetadata: false,
prerenderEarlyExit: true,
serverMinification: true,
linkNoTouchStart: false,
......@@ -2454,6 +2456,7 @@ export interface NextConfigRuntime {
| 'dynamicOnHover'
| 'useOffline'
| 'optimisticRouting'
| 'parallelRouteMetadata'
| 'inlineCss'
| 'prefetchInlining'
| 'authInterrupts'
......@@ -2523,6 +2526,7 @@ export function getNextConfigRuntime(
dynamicOnHover: ex.dynamicOnHover,
useOffline: ex.useOffline,
optimisticRouting: ex.optimisticRouting,
parallelRouteMetadata: ex.parallelRouteMetadata,
inlineCss: ex.inlineCss,
prefetchInlining: ex.prefetchInlining,
authInterrupts: ex.authInterrupts,
......
export async function generateMetadata() {
await Promise.resolve()
throw new Error('unrendered slot metadata error')
}
export default function ErrorSlot() {
return <div>error slot</div>
}
import { ImageResponse } from 'next/og'
export function generateImageMetadata() {
if (process.env.NEXT_PHASE === 'phase-production-build') {
return [
{
id: 'image',
size: { width: 1200, height: 630 },
contentType: 'image/png',
},
]
}
throw new Error('unrendered slot image metadata error')
}
export default function OpenGraphImage() {
return new ImageResponse(<div>image error slot</div>)
}
export default function ImageErrorSlot() {
return <div>image error slot</div>
}
import { notFound } from 'next/navigation'
export function generateMetadata() {
notFound()
}
export default function Login() {
return <div>login</div>
}
export async function generateViewport() {
await Promise.resolve()
throw new Error('unrendered slot viewport error')
}
export default function ViewportErrorSlot() {
return <div>viewport error slot</div>
}
import type { ReactNode } from 'react'
import { connection } from 'next/server'
export const metadata = {
title: {
default: 'conditional layout title',
template: '[%s]',
},
}
export default async function Layout({
children,
}: {
children: ReactNode
error: ReactNode
imageError: ReactNode
login: ReactNode
viewportError: ReactNode
}) {
// This route intentionally contains a regular metadata error in an
// unrendered slot. Keep it request-rendered so the production build can
// exercise the outlet behavior at request time.
await connection()
return children
}
export const metadata = {
title: 'conditional children title',
}
export default function Page() {
return <div id="conditional-children">conditional children</div>
}
import { markGeneratorStarted } from '../state'
export function generateMetadata() {
markGeneratorStarted('slot')
return { title: 'eager slot title' }
}
export function generateViewport() {
markGeneratorStarted('slot-viewport')
return { width: 'device-width' }
}
export default function Page() {
return <div id="eager-slot">eager slot</div>
}
import type { ReactNode } from 'react'
import { waitForGenerator } from './state'
export async function generateMetadata() {
let timeout: NodeJS.Timeout
const generatorsStartedEagerly = await Promise.race([
Promise.all([waitForGenerator('children'), waitForGenerator('slot')]).then(
() => true
),
new Promise<boolean>((resolve) => {
timeout = setTimeout(() => resolve(false), 5000)
}),
])
clearTimeout(timeout!)
return {
description: generatorsStartedEagerly
? 'parallel generators started eagerly'
: 'parallel generators were serialized',
}
}
export async function generateViewport() {
let timeout: NodeJS.Timeout
const generatorsStartedEagerly = await Promise.race([
Promise.all([
waitForGenerator('children-viewport'),
waitForGenerator('slot-viewport'),
]).then(() => true),
new Promise<boolean>((resolve) => {
timeout = setTimeout(() => resolve(false), 5000)
}),
])
clearTimeout(timeout!)
return {
colorScheme: generatorsStartedEagerly
? ('dark' as const)
: ('light' as const),
}
}
export default function Layout({
children,
slot,
}: {
children: ReactNode
slot: ReactNode
}) {
return (
<main>
{children}
{slot}
</main>
)
}
import { markGeneratorStarted } from './state'
export function generateMetadata() {
markGeneratorStarted('children')
return { title: 'eager children title' }
}
export function generateViewport() {
markGeneratorStarted('children-viewport')
return { width: 'device-width' }
}
export default function Page() {
return <div id="eager-children">eager children</div>
}
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