Metadata and SEO in Next.js

Analogy categoryAnalogies

Static Metadata with the metadata Object

In the App Router, a page or layout can export a metadata object typed as Metadata from next, which Next.js reads at build or request time to generate the corresponding <head> tags like <title> and <meta name="description">, replacing the old pages router pattern of manually rendering next/head. Metadata defined in a layout applies to every page beneath it and is merged with, not simply overridden by, metadata exported from nested pages: fields like title use a template mechanism where a layout can define title: { template: '%s | Acme', default: 'Acme' } and a page just sets title: 'Pricing' to produce 'Pricing | Acme'. This static approach is ideal for content that doesn't depend on runtime data, such as a marketing site's fixed pages.

🏏

Cricket analogy: The metadata template system is like a team's fixed jersey design with a blank space for the player's name, the sponsor logo and colors (the layout template) stay constant while each player's name (the page title) is swapped in.

Dynamic Metadata with generateMetadata

When a page's title or description depends on fetched data, such as a blog post's actual headline or a product's name and price, you export an async generateMetadata function instead of a static metadata object; it receives the same params and searchParams props as the page component and can await data fetching before returning a Metadata object. Next.js automatically deduplicates fetch calls, so if generateMetadata and the page component both call the same fetch for the same post, the underlying request only actually executes once thanks to the built-in fetch cache during a single render pass. generateMetadata can also accept a parent parameter, a Promise resolving to the metadata already resolved by parent segments, allowing you to read and extend inherited values like openGraph images rather than overwriting them.

🏏

Cricket analogy: generateMetadata pulling live data is like a scoreboard operator updating the 'player of the match' name only after the presentation ceremony data is confirmed, rather than displaying a placeholder set before the game even started.

tsx

// app/blog/[slug]/page.tsx
import type { Metadata, ResolvingMetadata } from 'next';

type Props = { params: Promise<{ slug: string }> };

export async function generateMetadata(
  { params }: Props,
  parent: ResolvingMetadata
): Promise<Metadata> {
  const { slug } = await params;
  const post = await getPostBySlug(slug);
  const previousImages = (await parent).openGraph?.images ?? [];

  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      images: [post.coverImage, ...previousImages],
    },
  };
}

export default async function BlogPost({ params }: Props) {
  const { slug } = await params;
  const post = await getPostBySlug(slug);
  return <article><h1>{post.title}</h1></article>;
}

Open Graph, Twitter Cards, and Structured Data

The Metadata object's openGraph field controls how a page appears when shared on platforms like Facebook, LinkedIn, or Slack, letting you set og:title, og:description, og:image, and og:type; the separate twitter field configures Twitter/X's card rendering, and setting twitter: { card: 'summary_large_image' } produces a prominent image preview rather than a small thumbnail. For structured data that search engines use to render rich results, such as star ratings on a recipe or a product's price, Next.js doesn't provide a dedicated API; instead you render a <script type="application/ld+json"> tag directly in your Server Component containing JSON-LD that follows schema.org vocabulary, which Google's crawler parses independently of the metadata object.

🏏

Cricket analogy: Open Graph tags are like the pre-match graphic broadcasters prepare with both team logos and the venue name, a standardized preview package other channels can pull from when promoting the match.

Sitemaps, robots.txt, and Metadata File Conventions

Next.js supports generating sitemap.xml and robots.txt dynamically by creating sitemap.ts and robots.ts files in the app directory: sitemap.ts exports a default function returning an array of objects with url, lastModified, changeFrequency, and priority fields, while robots.ts returns an object describing crawl rules and pointing to the sitemap's URL. These files are especially useful for dynamic content, since sitemap.ts can fetch every blog post or product ID from your database and generate a complete, always-current sitemap without maintaining a static XML file by hand. Next.js also supports static file conventions for favicon.ico, icon.png, and opengraph-image.png placed directly in a route segment, which are automatically picked up and linked in the page's generated metadata without any explicit configuration.

🏏

Cricket analogy: A dynamically generated sitemap.ts is like a tournament's fixture list auto-updating from the official schedule database, always current, rather than a fan manually retyping match dates on a printed flyer.

Next.js automatically infers metadataBase from the deployment URL in many hosting environments, but it's best practice to explicitly set metadataBase: new URL('https://example.com') in your root layout's metadata so that relative image URLs in openGraph and twitter fields resolve to correct absolute URLs across all environments, including local development and preview deployments.

Both the static metadata object and the generateMetadata function can only be exported from Server Components — a page or layout marked with 'use client' cannot export metadata at all. If a route needs client interactivity, keep the metadata export in a Server Component page.tsx or layout.tsx and move interactive logic into a separate imported Client Component.

The static metadata object export generates <head> tags like title and description automatically in the App Router.
Title templates defined in a layout are inherited and filled in by child pages via title: { template, default }.
generateMetadata is an async function used when metadata depends on fetched data, receiving the same params as the page.
The parent argument to generateMetadata lets you read and extend metadata resolved by parent segments.
openGraph and twitter fields control link preview rendering on social platforms and messaging apps.
JSON-LD structured data for rich search results is added manually via a <script type="application/ld+json"> tag.
sitemap.ts and robots.ts generate dynamic, always-current sitemap.xml and robots.txt files from live data.
metadata and generateMetadata can only be exported from Server Components, never from files marked 'use client'.