Metadata & SEO

The App Router has three ways to produce <head> content. They can be combined, and Next.js merges them into one set of tags per route.

Four rules hold for all of them:

Two tags are always present even when a route defines nothing: <meta charset="utf-8"> and <meta name="viewport" content="width=device-width, initial-scale=1">.

Source: Getting Started: Metadata and OG images

The root layout of the scratch app sets the defaults for every route below it.

Source: generateMetadata: the metadata object

Three fields in this snippet deserve a closer look.

title as an object. A string is the title of the route. An object has three keys:

metadataBase. Open Graph images, canonical links and alternates must be absolute URLs. With metadataBase set, every URL-based field in that segment and below may be a relative path, and Next.js composes the full URL (/en/books/1 becomes https://bookshelf.example.com/en/books/1, and duplicate slashes are normalised). Without it, the build prints a warning and resolves social image URLs against http://localhost:3000, which is wrong in production:

Set it once, in the root layout, from a constant or an environment variable that holds the canonical origin of your site.

viewport is not part of metadata. Theme colour, colour scheme and the viewport meta tag moved to their own export in Next.js 14; see Viewport: viewport and generateViewport.

generateMetadata receives the same params and searchParams promises as the page, plus a parent argument that resolves the metadata of the parent segments (useful to extend, say, the parent’s openGraph.images). Since Next.js 15 params is a promise, so it is awaited. The book page of the scratch app uses it for the title, the description, the canonical URL, the language alternates and the Open Graph card.

Source: generateMetadata

getBook is wrapped in React’s cache, so the page, generateMetadata and the image generator below share one lookup per request instead of three:

fetch calls with identical arguments are memoised automatically across generateMetadata, generateStaticParams, layouts and pages; cache is the tool for anything that is not fetch (a database client, an ORM).

Source: React: cache

next build prerenders the book pages with generateStaticParams, and the resulting head is plain HTML. This is the relevant part of curl -s localhost:3703/en/books/1, trimmed to the tags this section is about:

Things to read off that output: the layout’s template produced the title; the twitter:title and twitter:image were inherited from openGraph (Next.js falls back to the Open Graph values when twitter does not set them); the og:image and its size and type came from the opengraph-image file (see File-Based Metadata); the manifest and the icons were added by file conventions without any code in the layout. The same build and the same curl were repeated with cacheComponents: true and produced the same head.

Since Next.js 14, themeColor, colorScheme and the viewport meta tag are no longer part of metadata; they have their own exports. The root layout above shows the static viewport object. When the value depends on the route, export generateViewport:

curl -s localhost:3703/en/vp returns <meta name="theme-color" content="orange"/>. As with metadata, a segment cannot export both viewport and generateViewport, and both are Server Component only. If the value does not depend on request data, prefer the static object. A codemod (metadata-to-viewport-export) migrates old metadata.themeColor and metadata.viewport exports.

Unlike metadata, viewport cannot be streamed, because it affects the first paint. Under Cache Components, a generateViewport that reads cookies(), headers(), params or searchParams forces the page to wait for it. The docs offer three fixes: cache the data with 'use cache', wrap the document <body> in a <Suspense> boundary so the shell ships first, or opt a segment out with instant = false.

Source: generateViewport

If generateMetadata is slow (a CMS call, say), blocking the whole response on it would delay the first byte of every dynamically rendered page. Since Next.js 15.2, for dynamically rendered pages Next.js therefore sends the UI first and streams the metadata once generateMetadata resolves; React then moves the tags into <head> on the client. Crawlers that execute JavaScript and read the final DOM, such as Googlebot, see correct metadata. Crawlers that only read the initial HTML, for example facebookexternalhit, Twitterbot, Slackbot or Bingbot, would miss it, so Next.js detects them by User-Agent (the HTML-limited bots) and blocks rendering until the metadata is ready, putting it in <head> as before. Prerendered pages are not affected: their metadata is resolved at build time.

To see it, the scratch app has a deliberately slow dynamic route whose metadata depends on searchParams:

Requesting it with three user agents and measuring when the first byte arrives and where <title> sits in the HTML:

The browser and Googlebot get the shell in milliseconds with the title streamed later; Twitterbot waits 500 ms and gets the title in <head>.

Source: generateMetadata: streaming metadata

Special files in a route segment generate the <head> tags for you. Each can be a static file or a .js/.ts/.tsx file that generates the content. Next.js serves static files with a hash in production so they can be cached for a long time, and it adds the matching <link> and <meta> tags with the correct URL, type and size.

Generated metadata files are special Route Handlers (see Route Handlers and Backend for Frontend) and are cached by default: they are produced at build time unless they use a request-time API, uncached data or a dynamic route segment config. This is why a sitemap.ts that reads a database is still a static file after next build.

Source: Metadata Files

Titles and descriptions describe a page to people. Structured data describes the entities on it to machines: a book with an author and a price, an article, an event. The format recommended by search engines is JSON-LD with the schema.org vocabulary. Next.js has no API for it: the docs recommend rendering a plain <script type="application/ld+json"> tag from a layout or a page. A native <script> is correct here: next/script is for executable code, and JSON-LD is data.

The one trap is JSON.stringify, which does not escape <. A title such as </script><script>alert(1)</script> stored in your database would close the tag and inject script. Replace < with its Unicode escape. A small component keeps that in one place:

The prerendered HTML contains it:

Take the values from the same server-side source as the visible page (the price here is rendered from the book record on the server, never from client input), so that the structured data cannot disagree with what the user sees. Validate output with Google’s Rich Results Test or the Schema Markup Validator; for type safety, the community package schema-dts types the objects. The <script> can sit in the body, as here, where the component streams in; JSON-LD is valid anywhere in the document.

Source: JSON-LD

alternates in the metadata produces the link tags that deal with duplicate and translated content:

A caveat from the scratch app that the /en/books/99 request showed: notFound() thrown inside a <Suspense> boundary after the shell was flushed cannot change the status code, so the response is 200 with <title>Book not found | Bookshelf</title> and <meta name="robots" content="noindex"/>. That noindex from generateMetadata is what keeps such URLs out of the index. If the status must be 404, call notFound() before any streaming starts (see Streaming and Suspense). The localisation side, with the proxy and the app/[locale] layout, is in Internationalization.

Source: generateMetadata: alternates

Crawlers fetch HTML, and some (Google) also run JavaScript in a second pass, later and with a rendering budget. What matters for SEO is therefore what is in the first HTML response. The Metadata API puts titles and tags in the first response for every server-rendered strategy and for prerendered pages; client-side rendering is the exception.

Two practical consequences follow. First, document.title = …​ or useEffect in a Client Component is not a substitute for the Metadata API, since it runs after hydration (see Hydration). Second, speed is part of SEO, because search engines take page experience (Core Web Vitals) into account: the performance page of this section covers them, and so does the SEO fundamentals page for the markup side (semantic HTML, headings, internal links, clean URLs). For the rendering modes themselves read Rendering Fundamentals, and for the React ideas behind them Server Rendering, SSG and React Server Components.

The Pages Router has no Metadata API. Tags are set with the Head component from next/head, in a page, inside _app or in components. This was built in the scratch app as pages/en/legacy.tsx:

The prerendered HTML contains the tags with a data-next-head attribute, which Next.js uses to manage them during client-side navigations. Rules that cause most bugs: give duplicate tags the same key (the last one wins), keep the tags as direct children of Head (or one fragment level), do not set attributes of <html> or <body> with it, and remember that its contents are cleared when the component unmounts. Scripts belong in next/script. Head content is rendered where the page is rendered, so it follows getStaticProps/getServerSideProps and is complete in the first HTML. For sitemaps and robots.txt the Pages Router has no convention: use a static file in public/, or a page or API route that returns XML or text.

Source: Pages Router: Head

next/head does not work in the app directory. The migration guide states that in the App Router it "is replaced" by the built-in metadata support, and moving a page means converting each <Head> into a metadata object or a generateMetadata function. The reasons are structural:

React 19 also renders <title>, <meta> and <link> elements placed anywhere in a component tree and hoists them to <head>. That is a React feature that works, but in a Next.js App Router project the documented, merge-aware way is still the Metadata API; mixing both makes tags harder to reason about.

next-seo was the usual way to get typed SEO components in the Pages Router (NextSeo, DefaultSeo, JSON-LD components). Its current line (7.3.0 on npm in 2026-10) is oriented to the App Router and provides JSON-LD components (for example ArticleJsonLd), while the NextSeo component for the Pages Router is documented separately. For meta tags, titles, canonical links and Open Graph in the App Router it duplicates the Metadata API, so a new project does not need it for them. For JSON-LD it is optional: a ten-line component, as shown above, does the same without a dependency. Keep it only if an existing Pages Router codebase relies on it, and plan the move to the Metadata API when you migrate to the App Router.

Source: App Router migration: Step 3, migrating next/head

Check what crawlers receive, not what the browser shows after hydration. A few commands are enough:

Always test against next build && next start, because next dev renders every route on demand and does not show the build-time resolution. Use the browser’s developer tools to inspect <head> after hydration, Google’s Rich Results Test for structured data, and the sharing debuggers of the social networks for cards (they cache aggressively, so re-scrape after a change).

Source: Metadata and OG images and generateMetadata

In 16.x the documentation also describes generateMetadata and generateViewport under Cache Components, including the blocking-prerender-metadata-runtime, blocking-prerender-metadata-dynamic and blocking-prerender-viewport-runtime errors and the dynamic marker pattern used above.