Keep metadata rendering stable across streaming modes (#97440)
## Motivation Streaming and blocking metadata previously used different rendering paths. Metadata placement should depend on when Next.js starts consuming the response, rather than requiring the metadata component itself to render outside Suspense. ## What this does Selected metadata now always renders through the same hidden Suspense boundary. For blocking responses, an always-present `MetadataBlocker` waits for the same cached resolution before Next.js pulls the response, ensuring metadata remains in the document head. `MetadataOutlet` remains a single promise. It renders inside Suspense for streaming responses and outside Suspense for blocking responses so navigation and regular errors retain their existing behavior. HTML-limited bot requests continue to bypass PPR shells. A prerendered shell has already closed its head before dynamic metadata resolves, so resuming that shell cannot provide blocking metadata in the raw head. ## Review notes - Metadata resolution still starts from a rendered component so the active `workUnitStore` and React cache scope are available. - Fizz may begin rendering before metadata settles; blocking is enforced before Next.js starts pulling the response. - The hidden wrapper keeps top-level suspenseful metadata out of the document preamble. Metadata tags hoist out, so the wrapper remains empty. - The Cache Components blocking and hydration coverage runs with parallel metadata both disabled and enabled. ## Verification - `pnpm build-all` - `pnpm test-start-turbo test/e2e/app-dir/metadata-streaming-cache-components/metadata-streaming-cache-components-custom-bots.test.ts` - `pnpm test-start-webpack test/e2e/app-dir/metadata-streaming-cache-components/metadata-streaming-cache-components-custom-bots.test.ts` <!-- NEXT_JS_LLM -->
Showing
Please
register
or
sign in
to comment