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.paramsandprops.searchParamsare Promises; always writeconst { slug } = await props.params. - Setting
metadataBase: new URL("https://www.devventa.com")in rootapp/layout.tsxeliminates relative URL warnings on social images. - Use
parent: ResolvingMetadatato inherit and merge OpenGraph images or titles from ancestor layouts. - Wrap data access functions in React
cache()sogenerateMetadataandpage.tsxshare 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.
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:
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.
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:
metadata.metadataBase is not set for resolving social open graph images, falling back to localhost:3000
Set metadataBase once in your root layout:
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:
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.
Dynamic canonical URLs and self-referencing links
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.
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,
},
};
}
| Field | Configuration | Crawler behavior |
|---|---|---|
alternates.canonical | Relative or absolute path | Tells search engines which URL represents master authority |
robots.index | true (default) or false | Controls whether page appears in search indices |
robots.follow | true (default) or false | Instructs bot whether to discover outbound links |
openGraph.type | article or website | Changes 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:
// 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:
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
paramsandsearchParamsas Promises in all Next.js 15 metadata signatures. - Define metadataBase in root layout. Set an absolute HTTPS origin once in
app/layout.tsxso all child canonicals and images resolve without warnings. - Deduplicate database queries. Wrap database calls in
React.cache()sogenerateMetadataand 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
generateMetadatafor standard meta tags and complement it with structured data components for rich snippets.
Common mistakes
- Synchronous params access. Writing
params.slugwithoutawait, triggering Next.js 15 runtime warnings. - Using next/head in App Router. Importing
Headfromnext/headin Server Components. It is completely deprecated in App Router. - Awaiting ResolvingMetadata unnecessarily. Awaiting
parentwhen child tags do not rely on ancestor values, adding an artificial evaluation delay. - Omission of metadataBase. Leaving
metadataBaseunset, causing OpenGraph images to emit fallback warnings on production builds. - Duplicating OpenGraph titles. Manually repeating the site brand suffix in
openGraph.titlewhentitle.templatealready 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?
What causes the metadataBase warning in Next.js?
Does generateMetadata cause duplicate database queries if page.tsx needs the same data?
How does ResolvingMetadata differ from standard parent inheritance?
Muhammad Kashif
Founder and editor of Devventa, covering AI coding assistants, Next.js and the modern AI development stack.





