How the Metadata API works
The two exports work only in Server Components, because Next.js resolves metadata on the server so it can go into the initial HTML. A single route segment can export either the metadata object or generateMetadata, not both. fetch calls inside generateMetadata are memoized, so the same request made in the page, layouts or generateStaticParams runs only once.
Metadata from the root layout down to the page is merged shallowly, so a nested object such as openGraph set in a page replaces the parent's whole openGraph object. A title.template set in a layout applies only to child route segments, not to the segment that defines it, and it requires title.default. metadataBase sets the base URL for URL-based fields; a relative path in such a field without metadataBase causes a build error.
Since Next.js 14, themeColor, colorScheme and viewport are deprecated in the metadata object and belong in the separate viewport configuration (generateViewport).
Metadata files, OG images and streaming
Special metadata files (favicon, icon, apple-icon, manifest.json, opengraph-image, twitter-image, robots.txt, sitemap.xml) are served with hashed URLs in production, and Next.js fills in the matching head tags, including URL, type and image size. When both exist, file-based metadata wins over values set in the metadata object or generateMetadata. An opengraph-image file may be at most 8 MB and a twitter-image at most 5 MB; larger files fail the build. Dynamic Open Graph images are generated in an opengraph-image.tsx file with the ImageResponse constructor from next/og, which renders JSX and CSS to an image.
Next.js 15.2 added streaming support to generateMetadata. For dynamically rendered pages, Next.js streams metadata separately and injects it into the HTML once generateMetadata resolves, so the visible UI is not blocked; prerendered pages resolve metadata at build time. Streaming metadata is turned off for crawlers that expect tags in the head, such as Twitterbot, Slackbot and Bingbot, which Next.js detects by User-Agent. The htmlLimitedBots config option customizes or disables this. With Cache Components enabled in Next.js 16, generateMetadata follows the same prerendering rules as other components, so metadata that reads runtime data or uncached fetches defers to request time.
How Pagepro uses the Metadata API
Nexity, the delivery system Pagepro uses for Next.js and Sanity builds, sets metadata through next/metadata on every document type. It also generates dynamic OG images, a sitemap and robots.txt automatically. For an SEO review of an existing Next.js site, see Next.js SEO optimization.
Sources
- generateMetadata (App Router API reference)Next.js · nextjs.org
- Metadata and OG images (Getting Started, App Router docs; lastUpdated 2026-08-25)Next.js · nextjs.org
- Metadata Files API Reference (App Router docs)Next.js · nextjs.org
- opengraph-image and twitter-image (App Router docs)Next.js · nextjs.org