[metadata] update metadat docs for streaming metadata (#76282)

vercel · Feb 24, 2025 · 165f9be · 165f9be
1 parent dc5dd46
commit 165f9be
Show file tree

Hide file tree

Showing 2 changed files with 21 additions and 3 deletions.
diff --git a/docs/01-app/04-api-reference/04-functions/generate-metadata.mdx b/docs/01-app/04-api-reference/04-functions/generate-metadata.mdx
@@ -46,7 +46,6 @@ export async function generateMetadata({ params }) {
 >
 > - The `metadata` object and `generateMetadata` function exports are **only supported in Server Components**.
 > - You cannot export both the `metadata` object and `generateMetadata` function from the same route segment.
-> - On the initial load, streaming is blocked until `generateMetadata` has fully resolved, including any content from `loading.js`.
 
 ## The `metadata` object
 
@@ -1198,9 +1197,28 @@ export const metadata = {
 }
 ```
 
+#### Streaming Metadata
+
+Starting from v15.2, metadata returned by `generateMetadata` will be streamed to the client. This allows Next.js to inject metadata into the HTML as soon as it's resolved.
+
+Since page metadata often primarily targets bots & crawlers, Next.js will continue to block the render until the metadata is resolved for **HTML-limited bots**.
+
+Some bots, like `Googlebot`, can execute JavaScript and are able to inspect the full page DOM, meaning they **don't** require blocking metadata. However, bots like `Twitterbot` **cannot** execute JavaScript while crawling a page—they fall into the **HTML-limited** category.
+
+Next.js automatically detects the user agent of incoming requests to determine whether to serve streaming metadata or fallback to blocking metadata.
+
+If you need to customize this list, you can define them manually using the `htmlLimitedBots` option in `next.config.js`. Next.js will ensure user agents matching this regex receive blocking metadata when requesting your web page.
+
+```js filename="next.config.js"
+module.exports = {
+  htmlLimitedBots: 'MySpecialBot|MyAnotherSpecialBot|SimpleCrawler',
+}
+```
+
 ## Version History
 
 | Version   | Changes                                                                                                                                                 |
 | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `v15.2.0` | introduced streaming support to `generateMetadata`.                                                                                                     |
 | `v13.2.0` | `viewport`, `themeColor`, and `colorScheme` deprecated in favor of the [`viewport` configuration](/docs/app/api-reference/functions/generate-viewport). |
 | `v13.2.0` | `metadata` and `generateMetadata` introduced.                                                                                                           |
diff --git a/packages/next/src/server/config-shared.ts b/packages/next/src/server/config-shared.ts
@@ -1069,8 +1069,8 @@ export interface NextConfig extends Record<string, any> {
   }
 
   /**
-   * User agent of bots that should opt-out streaming metadata.
-   * User agents that pass this regex will block rendering until metadata has resolved, to ensure it's available in the `head` of the document.
+   * User Agent of bots that can handle streaming metadata.
+   * Besides the default behavior, Next.js act differently on serving metadata to bots based on their capability.
    */
   htmlLimitedBots?: RegExp
 }