Unverified Commit 165f9be7 authored by Jiachi Liu's avatar Jiachi Liu Committed by GitHub

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

parent dc5dd46f
...@@ -46,7 +46,6 @@ export async function generateMetadata({ params }) { ...@@ -46,7 +46,6 @@ export async function generateMetadata({ params }) {
> >
> - The `metadata` object and `generateMetadata` function exports are **only supported in Server Components**. > - 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. > - 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 ## The `metadata` object
...@@ -1198,9 +1197,28 @@ export const metadata = { ...@@ -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 History
| Version | Changes | | 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` | `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. | | `v13.2.0` | `metadata` and `generateMetadata` introduced. |
...@@ -1069,8 +1069,8 @@ export interface NextConfig extends Record<string, any> { ...@@ -1069,8 +1069,8 @@ export interface NextConfig extends Record<string, any> {
} }
/** /**
* User agent of bots that should opt-out streaming metadata. * User Agent of bots that can handle 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. * Besides the default behavior, Next.js act differently on serving metadata to bots based on their capability.
*/ */
htmlLimitedBots?: RegExp htmlLimitedBots?: RegExp
} }
......
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