Web Development

Next.js Metadata API SEO: A Practical Setup Guide

Next.js Metadata API SEO explained: title templates, metadataBase, canonicals, generateMetadata, robots, Open Graph overwrites and social images.

SJ SinanSJ Sinan9 min read
In this article

You’ve built a Next.js site, and every page shares the same title. Or the titles work, but social previews show the wrong image, and Search Console says Google picked a different canonical than you wanted. All of these come back to one place: how you set up metadata.

This guide covers Next.js Metadata API SEO in the App Router, field by field, with the setup I use on client sites and on sjsinan.com. No fluff, just what each option does and the mistakes to avoid.

Quick answer: For Next.js Metadata API SEO, set metadataBase and a title template in the root layout, export a metadata object from static pages, and use generateMetadata for dynamic pages. Give every page a unique title, description and canonical URL, set Open Graph fields from a shared base, and control indexing with the robots field.

How the Metadata API Works

The Next.js metadata documentation describes three ways to define metadata:

  • A static metadata object exported from a layout.js or page.js
  • A generateMetadata function for metadata that depends on data, like a blog post’s title
  • Special files such as opengraph-image.jpg, sitemap.js and robots.js

Next.js turns these into the right tags in the page head. One important limit: metadata and generateMetadata only work in Server Components. If a page file has 'use client' at the top, you can’t export metadata from it. Split it into a server page.js that exports metadata and a client component for the interactive parts.

The Root Layout: Set It Once

Your root app/layout.js should define the defaults every page inherits:

FieldWhat to setWhy it matters
metadataBaseYour live domain, like https://example.comLets every other URL field use relative paths
title.defaultYour brand or homepage titleUsed on pages that don’t set their own title
title.template%s plus a separator and your brandAdds your brand to every child page title
descriptionA general site descriptionFallback for pages without their own
openGraphSite name, locale, type, default imageBase for social previews
verificationYour Google Search Console codeVerifies ownership without a separate file

The generateMetadata reference notes that using a relative URL without metadataBase causes a build error, so set it first.

Titles: Templates, Defaults and Absolute

The title template is the best time saver in the whole API, but it has rules that confuse people:

  • title.template applies only to child segments, not to the page in the same folder.
  • You must also set title.default when you use a template.
  • A page that sets title: 'Services' becomes “Services | Your Brand” automatically.
  • Use title.absolute when a page needs a title without the template, such as the homepage.

Keep the final title under about 60 characters, including the brand suffix. If your template adds 15 characters, write page titles of 45 or fewer.

Descriptions and Canonical URLs

Every indexable page should have its own description. Duplicates across many pages give Google no reason to use yours, and it will write its own snippet instead.

Set the canonical with alternates.canonical on every page. With metadataBase in place, a relative path like /services/seo-audit/ is enough. Match your real URL format exactly. If your site uses trailingSlash: true, every canonical needs the trailing slash, or it points to a URL that only redirects.

For multilingual sites, alternates.languages creates hreflang tags for each language version.

Dynamic Pages With generateMetadata

For blog posts, products or case studies, fetch the data and return the fields:

  1. Read the slug from params (it’s a promise in current Next.js versions, so await it).
  2. Fetch the post with the same function the page uses.
  3. Return the title, description, canonical and Open Graph fields from that data.
  4. If the post doesn’t exist, call notFound() so the page returns a real 404.

The page and generateMetadata often need the same data. Wrap your fetch function in React’s cache so it only runs once per request, as the Next.js docs recommend. On my site, the WordPress post title becomes the page title, and the WordPress excerpt becomes the meta description, so editors control both from the CMS.

Next.js Metadata API SEO Trap: Open Graph Overwrites

This is the mistake I see most. Metadata from different route segments is merged shallowly. The docs say nested fields like openGraph and robots defined in an earlier segment are overwritten by the last segment that defines them.

So if your layout sets openGraph with a site name, locale and default image, and a page sets openGraph: { title: 'About' }, the page loses everything else. Social previews then show no image and no site name.

The fix is simple. Keep a shared object, for example baseOpenGraph in a small SEO helper file, and spread it at the start of every page’s openGraph. That’s exactly how sjsinan.com handles it.

Controlling Indexing With robots

The robots field outputs a robots meta tag. Use it to noindex pages that shouldn’t appear in search, such as thank-you pages, internal search results or private dashboards. You can also set Google-specific rules through googleBot, like max-image-preview: large, which allows bigger image previews in results.

Remember that robots is also overwritten by child segments, not merged. Set it deliberately per page.

Social Images the Easy Way

Add an opengraph-image.jpg file in a route folder, and Next.js adds the right tags for that route and its children. For pages like blog posts, an opengraph-image.js file can generate a unique image from the post title with ImageResponse. Use 1200 × 630 pixels, the size most platforms expect.

How Bots Get Your Metadata

For dynamically rendered pages, newer Next.js versions can stream metadata after the page starts loading. According to the docs, streaming is disabled for bots that expect metadata in the head, detected by user agent, and the htmlLimitedBots option lets you change that list. Prerendered pages don’t stream at all, because their metadata is resolved at build time. For most marketing sites, static pages avoid the question entirely.

Check Your Work

Checking is the last step of Next.js Metadata API SEO, and the one most people skip. After deploying, view the page source and check the title, description, canonical, robots and Open Graph tags on a few page types. Test social previews with a sharing debugger, and confirm in Search Console’s URL Inspection tool that Google picked your canonical. For the wider checklist, see my Next.js SEO best practices guide.

Frequently Asked Questions

What is the Next.js Metadata API?

It’s the built-in way to set page titles, descriptions, canonical URLs, Open Graph tags, robots rules and other head tags in the App Router. You export a metadata object or a generateMetadata function from layouts and pages, and Next.js outputs the correct tags. It replaced the older next/head approach used in the Pages Router.

Why are my Open Graph images missing on some pages?

Usually because a page defines its own openGraph object, which replaces the one from your layout instead of merging with it. The page then loses the default image and site name. Spread a shared base Open Graph object into every page’s openGraph field, or add an opengraph-image file to the route folder.

Can I use generateMetadata in a client component?

No. Both metadata and generateMetadata only work in Server Components. If your page needs client-side features like animations or state, keep the page.js file as a server component that exports metadata and fetches data, then render a separate client component for the interactive parts.

Do I still need next/head in the App Router?

No. In the App Router, the Metadata API handles everything next/head used to do. Using next/head there won’t work as expected. If you’re migrating from the Pages Router, move titles, descriptions and other head tags into metadata exports or generateMetadata functions as you move each route.

How do I add a canonical URL in Next.js?

Set metadataBase to your domain in the root layout, then add alternates: { canonical: '/your-path/' } to each page’s metadata. For dynamic routes, build the path from the slug inside generateMetadata. Make sure it matches your actual URL format, including trailing slashes, so it doesn’t point to a redirect.

How do I set a different title for each page in Next.js?

Set a title template in your root layout, such as “%s | Your Brand”, then export a metadata object from each page with its own title. For dynamic pages like blog posts, use generateMetadata to build the title from the post data. Next.js fills the page title into the template automatically.

How do I noindex a single page in Next.js?

Export metadata from that page with robots set to index: false, and Next.js adds a noindex robots meta tag to the page. Use it for thank-you pages, internal search results or test pages. Don’t also block the page in robots.txt, because Google needs to crawl the page to see the noindex tag.

Final Thoughts

Good Next.js Metadata API SEO comes from a solid root layout, unique titles and descriptions on every page, correct canonicals, and a shared Open Graph base that child pages can’t accidentally wipe out. Set it up once properly, and every new page inherits the right defaults.

If you’d like help setting this up, take a look at my Next.js website development service or send me a message with your site.

Found this useful? Share it:
SJ Sinan

Written by

SJ Sinan

Web Developer, SEO Specialist & Digital Marketer

I build fast WordPress and Next.js websites, rank them on Google and run Meta and Google Ads for businesses around the world. Everything I write here comes from real client work.

Comments

Be the first to share your thoughts or ask a question.

Leave a comment

Your email will not be published. Comments appear after review.

Free consultation

Want Me to Do This For You?

Tell me about your business and goals. I will suggest the right service and send you a clear, fixed quote.

  • Free 30-minute strategy call
  • Honest advice, even if you need less
  • Fixed quote within 24 hours