vercel · huozhi · Feb 8, 2025 · Jan 27, 2025 · Feb 3, 2025 · Feb 4, 2025
diff --git a/packages/next/src/client/components/router-reducer/ppr-navigations.ts b/packages/next/src/client/components/router-reducer/ppr-navigations.ts
@@ -797,9 +797,6 @@ function finishPendingCacheNode(
   // a pending promise that needs to be resolved with the dynamic head from
   // the server.
   const head = cacheNode.head
-  // TODO: change head back to ReactNode when metadata
-  // is stably rendered in body
-  // Handle head[0] - viewport
   if (isDeferredRsc(head)) {
     head.resolve(dynamicHead)
   }

diff --git a/packages/next/src/export/types.ts b/packages/next/src/export/types.ts
@@ -62,6 +62,7 @@ export interface ExportPageInput {
   nextConfigOutput?: NextConfigComplete['output']
   enableExperimentalReact?: boolean
   sriEnabled: boolean
+  streamingMetadata: boolean | undefined
 }
 
 export type ExportRouteResult =

diff --git a/packages/next/src/export/worker.ts b/packages/next/src/export/worker.ts
@@ -253,6 +253,13 @@ async function exportPageImpl(
     )
   }
 
+  // During the export phase in next build, if it's using PPR we can serve streaming metadata
+  // when it's available. When we're building the PPR rendering result, we don't need to rely
+  // on the user agent. The result can be determined to serve streaming on infrastructure level.
+  const serveStreamingMetadata = Boolean(
+    isRoutePPREnabled && input.streamingMetadata
+  )
+
   const renderOpts: WorkerRenderOpts = {
     ...components,
     ...input.renderOpts,
@@ -262,6 +269,7 @@ async function exportPageImpl(
     disableOptimizedLoading,
     locale,
     supportsDynamicResponse: false,
+    serveStreamingMetadata,
     experimental: {
       ...input.renderOpts.experimental,
       isRoutePPREnabled,
@@ -416,6 +424,7 @@ export async function exportPages(
             debugOutput: options.debugOutput,
             enableExperimentalReact: needsExperimentalReact(nextConfig),
             sriEnabled: Boolean(nextConfig.experimental.sri?.algorithm),
+            streamingMetadata: nextConfig.experimental.streamingMetadata,
             buildId: input.buildId,
           }),
           // If exporting the page takes longer than the timeout, reject the promise.

diff --git a/packages/next/src/lib/metadata/async-metadata.tsx b/packages/next/src/lib/metadata/async-metadata.tsx
@@ -1,21 +1,13 @@
 'use client'
 
-import { use } from 'react'
-import { useServerInsertedHTML } from '../../client/components/navigation'
+import { use, type JSX } from 'react'
+import { useServerInsertedMetadata } from '../../server/app-render/metadata-insertion/use-server-inserted-metadata'
 
-// We need to wait for metadata on server once it's resolved, and insert into
-// the HTML through `useServerInsertedHTML`. It will suspense in <head> during SSR.
-function ServerInsertMetadata({ promise }: { promise: Promise<any> }) {
-  let metadataToFlush: React.ReactNode = use(promise)
-
-  useServerInsertedHTML(() => {
-    if (metadataToFlush) {
-      const flushing = metadataToFlush
-      // reset to null to ensure we only flush it once
-      metadataToFlush = null
-      return flushing
-    }
-  })
+function ServerInsertMetadata({ promise }: { promise: Promise<JSX.Element> }) {
+  // Apply use() to the metadata promise to suspend the rendering in SSR.
+  const metadata = use(promise)
+  // Insert metadata into the HTML stream through the `useServerInsertedMetadata`
+  useServerInsertedMetadata(() => metadata)
 
   return null
 }

diff --git a/packages/next/src/lib/metadata/metadata.tsx b/packages/next/src/lib/metadata/metadata.tsx
@@ -3,7 +3,7 @@ import type { GetDynamicParamFromSegment } from '../../server/app-render/app-ren
 import type { LoaderTree } from '../../server/lib/app-dir-module'
 import type { CreateServerParamsForMetadata } from '../../server/request/params'
 
-import { cache, cloneElement } from 'react'
+import { Suspense, cache, cloneElement } from 'react'
 import {
   AppleWebAppMeta,
   FormatDetectionMeta,
@@ -38,6 +38,7 @@ import {
   VIEWPORT_BOUNDARY_NAME,
 } from './metadata-constants'
 import { AsyncMetadata } from './async-metadata'
+import { isPostpone } from '../../server/lib/router-utils/is-postpone'
 
 // Use a promise to share the status of the metadata resolving,
 // returning two components `MetadataTree` and `MetadataOutlet`
@@ -147,8 +148,8 @@ export function createMetadataComponents({
   async function resolveFinalMetadata() {
     try {
       return await metadata()
-    } catch (error) {
-      if (!errorType && isHTTPAccessFallbackError(error)) {
+    } catch (metadataErr) {
+      if (!errorType && isHTTPAccessFallbackError(metadataErr)) {
         try {
           return await getNotFoundMetadata(
             tree,
@@ -158,7 +159,18 @@ export function createMetadataComponents({
             createServerParamsForMetadata,
             workStore
           )
-        } catch {}
+        } catch (notFoundMetadataErr) {
+          // In PPR rendering we still need to throw the postpone error.
+          // If metadata is postponed, React needs to be aware of the location of error.
+          if (isPostpone(notFoundMetadataErr)) {
+            throw notFoundMetadataErr
+          }
+        }
+      }
+      // In PPR rendering we still need to throw the postpone error.
+      // If metadata is postponed, React needs to be aware of the location of error.
+      if (isPostpone(metadataErr)) {
+        throw metadataErr
       }
       // We don't actually want to error in this component. We will
       // also error in the MetadataOutlet which causes the error to
@@ -168,10 +180,15 @@ export function createMetadataComponents({
     }
   }
   async function Metadata() {
+    const promise = resolveFinalMetadata()
     if (serveStreamingMetadata) {
-      return <AsyncMetadata promise={resolveFinalMetadata()} />
+      return (
+        <Suspense fallback={null}>
+          <AsyncMetadata promise={promise} />
+        </Suspense>
+      )
     }
-    return await resolveFinalMetadata()
+    return await promise
   }
 
   Metadata.displayName = METADATA_BOUNDARY_NAME