diff --git a/docs/01-app/01-getting-started/14-metadata-and-og-images.mdx b/docs/01-app/01-getting-started/14-metadata-and-og-images.mdx index c41b578e8ed1..2d5c11f50179 100644 --- a/docs/01-app/01-getting-started/14-metadata-and-og-images.mdx +++ b/docs/01-app/01-getting-started/14-metadata-and-og-images.mdx @@ -113,7 +113,13 @@ export async function generateMetadata({ params, searchParams }, parent) { export default function Page({ params, searchParams }) {} ``` -Behind-the-scenes, Next.js will stream metadata separately from the UI and inject the metadata into the HTML as soon as it's resolved. +### Streaming metadata + +For dynamically rendered pages, if resolving `generateMetadata` might block rendering, Next.js streams the resolved metadata separately and injects it into the HTML as soon as it's ready. + +Statically rendered pages don’t use this behavior since metadata is resolved at build time. + +Learn more about [streaming metadata](/docs/app/api-reference/functions/generate-metadata#streaming-metadata). ### Memoizing data requests diff --git a/docs/01-app/03-api-reference/04-functions/generate-metadata.mdx b/docs/01-app/03-api-reference/04-functions/generate-metadata.mdx index 770fe8aa2961..75ed9d1ce191 100644 --- a/docs/01-app/03-api-reference/04-functions/generate-metadata.mdx +++ b/docs/01-app/03-api-reference/04-functions/generate-metadata.mdx @@ -1174,7 +1174,9 @@ There are two default `meta` tags that are always added even if a route doesn't Metadata returned by `generateMetadata` is streamed to the client. This allows Next.js to inject metadata into the HTML as soon as it's resolved. -Since page metadata primarily targets bots and crawlers, Next.js will stream metadata for bots that can execute JavaScript and inspect the full page DOM (e.g. `Googlebot`). However, metadata will continue blocking the render of the page for **HTML-limited** bots (e.g. `Twitterbot`) as these cannot execute JavaScript while crawling. +Streamed metadata is appended to the `` tag. Since metadata mainly targets bots and crawlers, Next.js streams metadata for bots that can execute JavaScript and inspect the full DOM (e.g. `Googlebot`). We have verified that these bots interpret the metadata correctly. + +For **HTML-limited** bots that can’t run JavaScript (e.g. `Twitterbot`), metadata continues to block page rendering and is placed in the `` tag. Next.js automatically detects the user agent of incoming requests to determine whether to serve streaming metadata or fallback to blocking metadata. @@ -1196,7 +1198,9 @@ module.exports = { } ``` -Specifying a `htmlLimitedBots` config will override the Next.js' default list, allowing you full control over what user agents should opt into this behavior. This is advanced behavior, and the default should be sufficient for most cases. +Specifying a `htmlLimitedBots` config will override the Next.js' default list, allowing you full control over what user agents should opt into this behavior. + +Overriding `htmlLimitedBots` could lead to longer response times. Streaming metadata is an advanced feature, and the default should be sufficient for most cases. ### Ordering