Skip to content

NEXT.JS

Next.js 15 generateMetadata: Dynamic SEO & OpenGraph

Configure dynamic SEO metadata, canonical URLs, and OpenGraph inheritance in Next.js 15 App Router using generateMetadata and ResolvingMetadata.

Next.js 15 generateMetadata delivers type-safe, dynamic SEO tags, canonical URLs, and OpenGraph cards directly from Server Components. In Next.js 15, params and searchParams are asynchronous Promises that must be awaited, preventing layout shift in streaming HTML and ensuring search engines receive fully resolved meta tags on initial crawl.

Unlike legacy next/head tags placed inside component bodies, generateMetadata executes before page streaming begins. It generates standards-compliant <meta>, <link rel="canonical">, and social tags with automatic deduplication across your route hierarchy.

Key takeaways

  • In Next.js 15, props.params and props.searchParams are Promises; always write const { slug } = await props.params.
  • Setting metadataBase: new URL("https://www.devventa.com") in root app/layout.tsx eliminates relative URL warnings on social images.
  • Use parent: ResolvingMetadata to inherit and merge OpenGraph images or titles from ancestor layouts.
  • Wrap data access functions in React cache() so generateMetadata and page.tsx share query results without hitting databases twice.
  • Always strip query parameters from canonical URLs to prevent duplicate content indexing across faceted filters.

The Next.js 15 metadata evaluation contract

Next.js App Router separates metadata generation from visual component rendering. You export either a static metadata object or an async generateMetadata function from any layout.tsx or page.tsx.

Terminal
npm run check:metadata-contract
# check:metadata-contract — 6 guards
# ok   all 6 metadata contract assertions passed.

When a crawler requests a page, Next.js evaluates the metadata function concurrently with the route segment:

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

type Props = {
  params: Promise<{ category: string; slug: string }>;
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
};

export async function generateMetadata(
  { params, searchParams }: Props,
  parent: ResolvingMetadata
): Promise<Metadata> {
  const { category, slug } = await params;
  return {
    title: `Guide: ${slug}`,
    description: `Technical deep dive into ${category}/${slug}.`,
  };
}

Metadata generated in child routes shallow-merges over parent layouts. Fields defined on a child page override parent values, while omitted fields fall back to parent defaults.

Resolving async params and searchParams promises

The defining breaking change in Next.js 15 is asynchronous dynamic parameters. In Next.js 14, params was a synchronous object. In Next.js 15, accessing params.slug directly throws a runtime warning and triggers compiler bailouts.

app/articles/[slug]/page.tsx
import { notFound } from "next/navigation";
import { getArticleBySlug } from "@/lib/articles";

export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
  // Correct Next.js 15 syntax
  const { slug } = await params;
  const article = await getArticleBySlug(slug);

  if (!article) {
    return { title: "Article Not Found" };
  }

  return {
    title: article.title,
    description: article.deck,
    alternates: {
      canonical: `/articles/${slug}`,
    },
  };
}

If you access searchParams, remember that search parameters opt the route into dynamic request-time rendering unless handled inside a static shell with connection().

Configuring metadataBase to prevent relative URL warnings

When configuring OpenGraph images or canonical links, search crawlers (including Googlebot and Twitterbot) require absolute URLs including protocol and hostname.

Without metadataBase, writing openGraph: { images: ["/og.png"] } causes Next.js to log:

Terminal
metadata.metadataBase is not set for resolving social open graph images, falling back to localhost:3000

Set metadataBase once in your root layout:

app/layout.tsx
import type { Metadata } from "next";

const siteOrigin = process.env.NEXT_PUBLIC_SITE_URL || "https://www.devventa.com";

export const metadata: Metadata = {
  metadataBase: new URL(siteOrigin),
  title: {
    template: "%s | Devventa",
    default: "Devventa — AI Dev Tools & Next.js Workflows",
  },
  description: "Independent engineering audits, technical benchmarks, and Next.js guides.",
  openGraph: {
    type: "website",
    locale: "en_US",
    siteName: "Devventa",
  },
};

Once defined in app/layout.tsx, all relative strings passed to alternates.canonical, openGraph.images, and twitter.images throughout child pages automatically resolve against this base URL.

Inheriting parent metadata with ResolvingMetadata

In complex nested layouts (e.g., app/(marketing)/blog/[slug]/), you often want to append an article-specific image to an existing OpenGraph image array defined by a parent section.

The parent parameter provides read access to the resolved ancestor metadata tree:

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

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

  return {
    title: `Post ${slug}`,
    openGraph: {
      images: [`/articles/${slug}/cover.webp`, ...previousImages],
    },
  };
}

Awaiting parent introduces an execution sequence: child metadata evaluation waits for parent layout metadata to resolve first. Use this only when you genuinely depend on parent properties; avoid awaiting parent if your page defines all its meta tags independently.

Faceted navigation, tracking parameters (utm_source), and pagination often generate duplicate content flags in Google Search Console. Setting an explicit self-referencing canonical URL in generateMetadata resolves this indexing trap.

app/catalog/page.tsx
import type { Metadata } from "next";

type Props = {
  searchParams: Promise<{ page?: string; tag?: string }>;
};

export async function generateMetadata({ searchParams }: Props): Promise<Metadata> {
  const { page, tag } = await searchParams;
  const pageNum = Number.parseInt(page || "1", 10);

  // Canonical ignores tracking query params, keeping clean self-referencing paths
  const canonicalPath = tag
    ? `/catalog?tag=${encodeURIComponent(tag)}${pageNum > 1 ? `&page=${pageNum}` : ""}`
    : `/catalog${pageNum > 1 ? `?page=${pageNum}` : ""}`;

  return {
    title: tag ? `Catalog: ${tag}` : "Full Catalog",
    alternates: {
      canonical: canonicalPath,
    },
  };
}
FieldConfigurationCrawler behavior
alternates.canonicalRelative or absolute pathTells search engines which URL represents master authority
robots.indextrue (default) or falseControls whether page appears in search indices
robots.followtrue (default) or falseInstructs bot whether to discover outbound links
openGraph.typearticle or websiteChanges social card format on Facebook and LinkedIn

What did not work: fetch waterfalls and double execution

During our initial metadata rollout, we called our database lookup helper in both generateMetadata and page.tsx:

app/reviews/[slug]/page.tsx
// BROKEN: Executes DB query twice per uncached render
export async function generateMetadata({ params }) {
  const { slug } = await params;
  const data = await queryDatabase(slug); // Query 1
  return { title: data.title };
}

export default async function Page({ params }) {
  const { slug } = await params;
  const data = await queryDatabase(slug); // Query 2 (Duplicate!)
  return <ArticleView article={data} />;
}

In serverless environments using raw database drivers (like Cloudflare D1 or PostgreSQL connection pools), this doubled database round-trip latency on cold requests.

The fix is React's cache() utility:

lib/get-article.ts
import { cache } from "react";
import { db } from "./db";

export const getArticle = cache(async (slug: string) => {
  return await db.articles.findUnique({ where: { slug } });
});

Because React memoizes cache() wrappers per request life cycle, the first caller (generateMetadata) triggers the database fetch, while the second caller (Page) receives the cached result instantly in zero milliseconds.

Best practices for Next.js metadata

  • Always await params. Treat params and searchParams as Promises in all Next.js 15 metadata signatures.
  • Define metadataBase in root layout. Set an absolute HTTPS origin once in app/layout.tsx so all child canonicals and images resolve without warnings.
  • Deduplicate database queries. Wrap database calls in React.cache() so generateMetadata and the page share one query execution.
  • Sanitize canonical paths. Never copy raw query strings into alternates.canonical; strip analytics tags to protect indexing authority.
  • Pair with JSON-LD. Use generateMetadata for standard meta tags and complement it with structured data components for rich snippets.

Common mistakes

  • Synchronous params access. Writing params.slug without await, triggering Next.js 15 runtime warnings.
  • Using next/head in App Router. Importing Head from next/head in Server Components. It is completely deprecated in App Router.
  • Awaiting ResolvingMetadata unnecessarily. Awaiting parent when child tags do not rely on ancestor values, adding an artificial evaluation delay.
  • Omission of metadataBase. Leaving metadataBase unset, causing OpenGraph images to emit fallback warnings on production builds.
  • Duplicating OpenGraph titles. Manually repeating the site brand suffix in openGraph.title when title.template already appends it.

Decision guide: static vs dynamic metadata

If a page has fixed copy known at build time (e.g. /about, /contact, /pricing), export a static export const metadata: Metadata = { ... } object. Static metadata requires zero compute overhead and serializes directly into the static HTML shell.

Use generateMetadata only when meta values depend on dynamic URL parameters, external CMS payloads, database rows, or query parameters. Combine it with generateStaticParams to prerender dynamic metadata into static HTML files at build time.

Frequently asked questions

Why are params and searchParams Promises in Next.js 15 generateMetadata?
Next.js 15 aligned metadata resolution with React 19 async request semantics. Because dynamic route parameters and search queries depend on the incoming request lifecycle, they must be explicitly awaited using const { slug } = await params to allow the compiler to optimize static and streaming execution boundaries.
What causes the metadataBase warning in Next.js?
The metadataBase warning appears when an OpenGraph image, Twitter card, or canonical link uses a relative path (such as /og-image.png) without a root URL defined in your root layout. Setting metadataBase: new URL('https://www.devventa.com') resolves relative strings into fully-qualified absolute URLs required by social crawlers.
Does generateMetadata cause duplicate database queries if page.tsx needs the same data?
No, provided you use React cache() or the native Next.js fetch Data Cache. React automatically deduplicates identical data requests across generateMetadata and your Server Component during the same render pass, executing the underlying database query or network fetch exactly once.
How does ResolvingMetadata differ from standard parent inheritance?
ResolvingMetadata is an async parameter passed to generateMetadata that gives you programmatic access to the resolved metadata object from parent layouts. This allows child pages to append OpenGraph image arrays or read parent title templates dynamically before returning the child metadata.

Muhammad Kashif

Founder and editor of Devventa, covering AI coding assistants, Next.js and the modern AI development stack.