Intense-Visions Next.js Metadata API
Define SEO metadata, Open Graph tags, and dynamic OG images with the Metadata API
When to Use
- Setting page titles, descriptions, and canonical URLs
- Generating Open Graph and Twitter Card metadata for social sharing
- Creating dynamic OG images for blog posts, product pages, or any dynamic content
- Configuring robots.txt behavior, sitemaps, and web app manifests
- Overriding metadata from a parent layout in a child page
Instructions
- Export a
metadataconstant from anylayout.tsxorpage.tsxfor static metadata. - Export an async
generateMetadata({ params, searchParams })function for dynamic metadata derived from route parameters or fetched data. - Use the
title.templateproperty in rootlayout.tsxto set a consistent title suffix — child pages set only the page-specific prefix. - Pass
metadataBasein root metadata to resolve relative URLs inopenGraph.imagesandtwitter.images. - Create
opengraph-image.tsxin any route segment to generate a dynamic OG image with@vercel/og— no external service needed. - Use
robots,canonical, andalternatesfields to control crawler behavior and avoid duplicate content. - Metadata is merged from parent layouts down to child pages — child values override parent values for the same key.
- Never duplicate metadata in both
layout.tsxandpage.tsxfor the same route — define at the most specific level.
// app/layout.tsx — root metadata with template and base URL
export const metadata: Metadata = {
metadataBase: new URL('https://example.com'),
title: { default: 'My App', template: '%s | My App' },
description: 'The best app in the world',
openGraph: { type: 'website', locale: 'en_US', siteName: 'My App' },
};
// app/posts/[slug]/page.tsx — dynamic metadata
import type { Metadata } from 'next';
export async function generateMetadata({ params }: { params: { slug: string } }): Promise<Metadata> {
const post = await fetchPost(params.slug);
return {
title: post.title, // becomes "Post Title | My App" via template
description: post.excerpt,
openGraph: {
title: post.title,
description: post.excerpt,
images: [{ url: `/api/og?title=${encodeURIComponent(post.title)}`, width: 1200, height: 630 }],
},
};
}
// app/posts/[slug]/opengraph-image.tsx — dynamic OG image
import { ImageResponse } from 'next/og';
export const runtime = 'edge';
export const size = { width: 1200, height: 630 };
export const contentType = 'image/png';
export default async function Image({ params }: { params: { slug: string } }) {
const post = await fetchPost(params.slug);
return new ImageResponse(<div style={{ fontSize: 48 }}>{post.title}</div>);
}
Details
The Metadata API replaces <Head> from next/head in the App Router. It is declarative, type-safe, and tree-mergeable — parent layout metadata flows down to child pages, with child values winning on conflict.
title.template: The root layout sets title: { default: 'My App', template: '%s | My App' }. Every child page that sets title: 'Dashboard' automatically becomes 'Dashboard | My App'. Pages that do not set a title fall back to default.
metadataBase: Required when any metadata field uses a relative URL (especially openGraph.images). Without it, Next.js warns and relative URLs are not resolved correctly for social crawlers.
Dynamic OG images with opengraph-image.tsx: Place this file in any route segment directory. It exports an ImageResponse and runs on the Edge Runtime. Next.js automatically serves it at /{route}/opengraph-image and links it from the page's <meta> tags. No additional configuration needed.
Deduplication: Next.js merges metadata from all parent layouts. If a parent sets openGraph.images and a child does not, the parent's images are used. If the child sets openGraph.images, it replaces the parent's entirely — not merged.
Sitemap and robots: Create app/sitemap.ts (returns MetadataRoute.Sitemap) and app/robots.ts (returns MetadataRoute.Robots) for programmatic control of these files.
Source
https://nextjs.org/docs/app/building-your-application/optimizing/metadata
Process
- Read the instructions and examples in this document.
- Apply the patterns to your implementation, adapting to your specific context.
- Verify your implementation against the details and edge cases listed above.
Harness Integration
- Type: knowledge — this skill is a reference document, not a procedural workflow.
- No tools or state — consumed as context by other skills and agents.
Success Criteria
- The patterns described in this document are applied correctly in the implementation.
- Edge cases and anti-patterns listed in this document are avoided.