Dynamic generateMetadata

Pricing — Acme works as a static string. /blog/why-postgres-wins cannot: the title must say "Why Postgres Wins", and that string exists only in the database row the URL points at. The static export's boundary — build-known values — is exactly what generateMetadata crosses: an async function exported from a page or layout that receives the route's params and returns a Metadata object at render time.

// app/blog/[slug]/page.tsx
import type { Metadata } from "next";
import { notFound } from "next/navigation";
import { getPost } from "@/lib/posts";

export async function generateMetadata(props: {
  params: Promise<{ slug: string }>;
}): Promise<Metadata> {
  const { slug } = await props.params;          // params is a Promise in Next 15
  const post = await getPost(slug);
  if (!post) notFound();
  return {
    title: post.title,
    description: post.excerpt,
    alternates: { canonical: `/blog/${post.slug}` },
  };
}

The props mirror the page's own: params (a Promise in the current release line — await it, as the page does) and searchParams, with the same segment-keyed shape. The return type is the same Metadata object from The Metadata API — everything typed there applies here; the only difference is that the values can now be computed from a fetched record. Merge semantics are unchanged: what this function returns merges up the layout tree exactly like a static export, so a root layout still supplies the brand template and metadataBase while the function supplies the record-specific fields.

One rule is enforced at build time, and it trips everyone once: a file may export either metadata or generateMetadata, never both. Ship both and the build fails with a message naming the file and the conflicting exports. The design reason is inheritance, not pedantry: the static object is the file's metadata; the function is the file's metadata. To keep a shared description at the layout level and vary only the title per record, you do not combine exports — you let the layout's static metadata provide the defaults and have each record's function return only what it knows.

Timing matters for reasoning about cost. generateMetadata runs during the same request render as the page — on the server, per request for dynamic routes, at build for prerendered paths. It is not a middleware, not a hook, not something the browser ever executes. Two consequences follow. First, it can use everything server code can: databases, cookies(), secrets. Second, on a prerendered route with generateStaticParams, the function runs once per path at build, so its fetches join the build's data budget — the fan-out math of Static Generation with generateStaticParams applies to metadata as much as to content.

The Pages Router had a weaker version — getServerSideProps could set res.setHeader("og:...", ...), and getStaticProps contexts received nothing useful for titles — which is why long-form record titles were an enduring pain before the App Router. If you are maintaining a codebase where every blog title is set through a client useEffect and next/head, this function is the migration target: same data, server-rendered, statically analyzable, and it participates in caching instead of fighting it.

The obvious implementation of record-driven metadata fetches the record twice: once inside generateMetadata for the title, once in the page for the content. Two queries per request for the same row — and on a prerendered route, twice per path per build. The fix is a shared, memoized accessor:

// lib/posts.ts
import { cache } from "react";

export const getPost = cache(async (slug: string) => {
  return db.post.findUnique({ where: { slug } });
});

// app/blog/[slug]/page.tsx
export async function generateMetadata(props: { params: Promise<{ slug: string }> }) {
  const { slug } = await props.params;
  const post = await getPost(slug);         // first call: executes the query
  if (!post) notFound();
  return { title: post.title, description: post.excerpt };
}

export default async function PostPage(props: { params: Promise<{ slug: string }> }) {
  const { slug } = await props.params;
  const post = await getPost(slug);         // same request: memoized — no second query
  if (!post) notFound();
  return <Article post={post} />;
}

React cache() memoizes per render pass, and Next.js runs generateMetadata and the page within the same pass — the two calls deduplicate into one database round trip. This is the same deduplication mechanism Server Components use for shared fetches, and it is the pattern that makes record-driven metadata affordable: the metadata no longer doubles your data-layer load. A fetch with identical URL and options dedupes the same way within one render; the explicit cache() wrapper exists precisely for the non-fetch data access (Prisma, Drizzle, filesystem reads) that the automatic dedup cannot see.

Error and empty-state handling inside the function has its own semantics, and getting them right is most of the battle with real content:

Calling notFound() in generateMetadata is worth internalizing: without it, a bad slug renders a page that throws a moment later — two failure paths, one of which produces a title full of undefined in the interim. With it, the missing-record decision is made once, before either the head or the body renders.

The performance envelope to state in interviews: metadata generation delays the response — the head is part of the first byte, so a slow metadata fetch delays everything, even if the page's own content would have been fast. Keep the metadata path lean (one indexed lookup, no N+1 enrichment), and where the data genuinely cannot be fast, consider deferring the heavy part: the openGraph.images generation of the next topic can point at a URL that resolves independently, while title and description — the fields crawlers act on — come from the cheap query. The instinct to treat metadata as a lightweight echo of data you already loaded is the correct one; cache() is how you make it literally true.

The title and description serve search results. A different consumer — Slack, Discord, iMessage, Twitter/X, LinkedIn — reads the og: and twitter: tags to render a link preview card, and its fetcher is a plain HTTP client with no JavaScript. generateMetadata is where those tags get their per-record values:

export async function generateMetadata(props: {
  params: Promise<{ slug: string }>;
}): Promise<Metadata> {
  const { slug } = await props.params;
  const post = await getPost(slug);
  if (!post) notFound();

  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      type: "article",
      url: `/blog/${post.slug}`,
      title: post.title,                    // falls back to `title` if omitted
      description: post.excerpt,
      publishedTime: post.publishedAt.toISOString(),
      images: [{ url: `/og/${post.slug}`, width: 1200, height: 630, alt: post.title }],
    },
    twitter: {
      card: "summary_large_image",
      title: post.title,
      description: post.excerpt,
      images: [`/og/${post.slug}`],
    },
  };
}

Read the field semantics carefully, because the two namespaces are not redundant. openGraph speaks the de-facto standard every platform half-supports; twitter overrides it on Twitter/X — omit the twitter fields and the platform falls back to the og: values, but card is the one field with no og: equivalent: summary (small square thumbnail) versus summary_large_image (the wide hero image most content sites want). Declaring both namespaces is not duplication; it is naming the fallback explicitly and overriding only where the platforms differ.

type changes which optional fields are legal: article unlocks publishedTime, authors, section; website is the safe default; product carries price fields — though a product's rich pricing preview comes from JSON-LD Structured Data, not from Open Graph alone. url sets the canonical link a card points back to — on a page with query-string variants, explicitly setting it stops ?ref=twitter from forking your previews into distinct cards.

The absolute-URL rule from the static topic applies with full force here: every image URL a card fetches must resolve publicly, and relative paths are resolved against metadataBase — without which the emitted URL points at http://localhost and every shared link renders with no image. On a prerendered route this whole function runs at build, so the card data is frozen with the page; on a dynamic route it runs per request. Either way the fetcher sees static HTML — the tags were rendered server-side before anything left the node process.

What ships next is the image itself: a per-record card can no longer be one file in /public forever — og/why-postgres.png does not exist until someone generates it. Next.js ships an image-generation route for exactly that (ImageResponse), and its constraints — which CSS subset satori accepts, which fonts load, how the generated image is cached — are the material of Open Graph and Twitter Cards. The metadata you just wrote is what will point at it.

Two field mechanics round out the set. The images array accepts multiple entries, but most scrapers take only the first — additional entries are fallbacks for platforms that reject the lead image's format or size, not a slideshow; put the 1200 × 630 card first and variants after it. And openGraph.locale ("en_US") plus locale: alternate entries declare the card's language variants, which matters on i18n sites where one URL serves several languages through negotiated or path-based routing — the locale tag tells the platform which card language matches the reader. Both mechanics share the discipline of everything in this function: the values come from the record, the URLs are absolute, and the head ships them with the response.