#Metadata
The Next.js Metadata API - metadata and generateMetadata in pages and layouts, merged in Next.js order, with real tags in the first bytes of the head.
A page declares its <head> tags with the Next.js Metadata API: an exported
metadata object, or an async generateMetadata({ params, searchParams }, parent)
that returns one. Layouts export them too. Krate resolves the chain from the root
layout down to the page and writes real tags into the <head> of the response, in
the initial HTML a crawler or link scraper reads, not patched in by script.
// src/pages/_layout.tsx
import type { Metadata } from "@krate/runtime/server";
export const metadata: Metadata = {
metadataBase: new URL("https://example.com"),
title: { default: "Example", template: "%s | Example" },
description: "The example site",
};// src/pages/blog/[slug].tsx
import type { Metadata, ResolvingMetadata } from "@krate/runtime/server";
export async function generateMetadata(
{ params }: { params: Promise<{ slug: string }> },
parent: ResolvingMetadata,
): Promise<Metadata> {
const { slug } = await params;
const post = await fetch(`https://api.example.com/posts/${slug}`, { next: { tags: ["posts"] } }).then((r) => r.json());
return {
title: post.title, // "Hello | Example"
description: post.summary,
alternates: { canonical: `/blog/${slug}` },
openGraph: { title: post.title, images: [post.cover] },
};
}
export default async function Post({ params }: { params: Promise<{ slug: string }> }) {
const { slug } = await params;
return <h1>{slug}</h1>;
}#When it runs
| Page | generateMetadata runs |
Tags are |
|---|---|---|
| Static (SSG) | once at build time | baked into index.html |
Static from generateStaticParams |
once per generated entry (one run for all entries) | baked into each entry's HTML |
| Dynamic route that stays a template | at build time, with the route's placeholders; the server fills in each request's value | baked into the template |
| SSR, ISR, async page | on every render, next to the page, in the same request and cache scope | sent in the head of the response; an ISR entry stores them with the body |
At build time the chain runs in the embedded JavaScript engine and falls back to
Node when it needs fetch or a Node built-in (the ssrRuntime or runtime setting, as for
generateStaticParams). Only the metadata, viewport and generateMetadata exports
of each file run, with what they use (the imports and module-level values they refer
to), not the page component or the rest of the module; a module that cannot be cut
that way (a let that other top-level code changes) runs whole. generateStaticParams
is evaluated the same way. On a request-time page the build bakes nothing from a chain
that has a generateMetadata: the renderer resolves the whole chain per request, so
the layout and page parts always agree.
generateMetadata receives { params, searchParams } that read both ways
(params.slug and (await params).slug) and a promise of the metadata resolved so
far. On a static page searchParams is empty.
Because it runs inside the render, it shares the page's data cache: a fetch with
next: { tags, revalidate } in generateMetadata and the same request in the page
reach the server once (concurrent identical cached requests are shared), the tags
are recorded on the page's ISR entry, and revalidateTag refreshes both. A
searchParams key it reads keys the ISR cache like one the page reads.
#Merge order
Segments are merged from the root layout to the page; a deeper segment wins. The rules are Next.js's:
- A field a deeper segment sets replaces the parent's value as a whole.
openGraph: { title }in a page drops the layout'sopenGraph.siteName; read the parent (const { openGraph } = await parent) to extend it. titleas a string takes the nearest ancestor'stitle.template("%s | Example").{ absolute }ignores templates;{ default, template }in a layout sets the default title and the template for its descendants (the template does not apply to the layout's owndefault).openGraph.titleandtwitter.titlehave their own templates, declared asopenGraph: { title: { default, template } }; the pagetitle.templatedoes not apply to them.metadataBaseresolves relative URLs inalternates,openGraph,twitter,iconsandmanifest; its path is a prefix.- An explicit
<Head>on the page still wins over its metadata for the same tag, and metadata wins over a layout's own head markup and the site-wideheadconfig.
On a request-time page the tags are merged into the head of the response by the same
rules <Head> uses (see Built-in components):
a tag replaces a baked tag with the same name, property or http-equiv, a
link rel="canonical" replaces the canonical link, og:image may repeat.
#Values inside <Head>
Tags written in <Head> (and <title>, <meta> and <link> rendered on
their own) are part of the static HTML, so their values are computed during the
build. Calls to helpers imported from your project work when the helper is plain
code: strings and templates, JSON, URL, encodeURIComponent and calls to
other project functions.
import { absoluteUrl, ogImage } from "../lib/seo";
<Head>
<link rel="canonical" href={absoluteUrl("/pricing")} />
<meta property="og:image" content={ogImage("pricing")} />
</Head>A value the build cannot compute (it reads the browser, the clock, process.env
or an object a class builds) is reported as warning KR8353, because crawlers would
see the tag without it. Compute it from plain values, pass it as a prop, or use
generateMetadata.
#Supported fields
title, description, applicationName, authors, generator, keywords,
referrer, creator, publisher, robots (a string, or an object with
googleBot), alternates (canonical, languages, media, types), openGraph
(including article and profile fields, images, videos, audio), twitter,
icons, manifest, themeColor, colorScheme, viewport, verification,
appleWebApp, formatDetection, category, itunes, appLinks, archives,
assets, bookmarks and other.
A static export const viewport = { width, initialScale, themeColor, colorScheme, ... }
is read too (the page's viewport meta replaces the default one). generateViewport
is not supported.
#Errors
A generateMetadata that throws never costs the page. The error is logged with the
file, the page renders without that segment's metadata (the other segments still
count), and the response stays 200. At build time the same failure is warning
KR7122, which also covers a metadata value that
cannot be computed at build time (a browser global, a service that is down); the
page still builds. Fix the cause, or render the page per request so
generateMetadata runs with the request.
notFound(), forbidden(), unauthorized() and redirect() called from
generateMetadata answer the request as they do from the page (404, 403, 401, a
redirect) on a request-time page.
#Limits
- A layout's
metadatais evaluated for every page below it; a layout'sgenerateMetadataruns for each of them too (per request on request-time pages). generateViewportandexport const dynamiceffects on metadata are not supported. Metadata files (sitemap.ts,opengraph-image, ...) are covered in Metadata routes.- A dynamic route served from its template cannot fetch per request. Use
generateStaticParams, or make the page request-time.
Last updated: 2026-11-17
Contributors: Noinkin