The Next.js Metadata API: a complete SEO setup that scales

How does the Metadata API work?

Each route segment can export a static metadata object or an async generateMetadata function; Next.js merges them from the root layout down to the page and renders the resulting head tags.

Merging is shallow per field. A child that defines openGraph replaces the parent's openGraph entirely rather than merging its keys, which is the source of most 'my OG image disappeared' reports. Compose deliberately with a helper instead of relying on inheritance for nested objects.

// app/layout.tsx
export const metadata: Metadata = {
  metadataBase: new URL("https://rovqix.in"),
  title: { default: "ROVQIX — Building Digital Products", template: "%s — ROVQIX" },
  alternates: { canonical: "/" },
  robots: { index: true, follow: true },
};

How do I set canonical URLs correctly?

Every indexable page needs a self-referencing canonical pointing at the exact URL you want ranked — one protocol, one host, no trailing-slash ambiguity, no tracking parameters. With metadataBase set, alternates.canonical accepts a path and Next.js resolves it to an absolute URL.

• Paginated listings: canonical to the page itself, not to page one.
• Filtered or sorted views: canonical to the unfiltered URL if the filtered version is not meant to rank.
• Duplicate content across locales: use alternates.languages with hreflang rather than a cross-locale canonical.
• Never canonicalise to a URL that redirects, 404s, or is blocked in robots.txt.

How do I generate Open Graph images automatically?

Place an opengraph-image.tsx file in a route segment and export a component built with ImageResponse. Next.js renders it to a PNG at build or request time and injects the correct og:image tags with dimensions — no design handoff, no stale assets, and every new page gets a branded card for free.

// app/blog/[slug]/opengraph-image.tsx
import { ImageResponse } from "next/og";

export const size = { width: 1200, height: 630 };
export const contentType = "image/png";

export default async function Image({ params }) {
  const { slug } = await params;
  const post = await getPost(slug);
  return new ImageResponse(<Card title={post.title} />, size);
}

How do sitemaps and robots.txt fit in?

Both are file conventions. app/sitemap.ts exports a function returning your URL entries, and app/robots.ts returns your crawl rules and sitemap location. Because they are code, they can read the same content source your pages read — which means a new article appears in the sitemap the moment it exists, with no manual step.

// app/sitemap.ts
export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  const posts = await getAllPosts();
  return [
    { url: "https://rovqix.in", lastModified: new Date(), priority: 1 },
    ...posts.map((post) => ({
      url: `https://rovqix.in/blog/${post.slug}`,
      lastModified: new Date(post.updatedAt),
    })),
  ];
}

How do you stop metadata drift across a growing site?

Centralise it. We build one typed helper that takes a content object and returns a complete Metadata result — title, description, keywords, canonical, robots, Open Graph and Twitter. Pages call the helper; nobody hand-writes tags. When we add a field, every page gets it in one commit.

1. 1A shared buildMetadata() helper used by every route.
2. 2A required description field on your content type so TypeScript blocks a page without one.
3. 3A build-time check that every sitemap URL returns a self-referencing canonical.
4. 4A crawl of the staging deployment before release to catch noindex left over from testing.