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
metadataobject exported from alayout.jsorpage.js - A
generateMetadatafunction for metadata that depends on data, like a blog post’s title - Special files such as
opengraph-image.jpg,sitemap.jsandrobots.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:
| Field | What to set | Why it matters |
|---|---|---|
metadataBase | Your live domain, like https://example.com | Lets every other URL field use relative paths |
title.default | Your brand or homepage title | Used on pages that don’t set their own title |
title.template | %s plus a separator and your brand | Adds your brand to every child page title |
description | A general site description | Fallback for pages without their own |
openGraph | Site name, locale, type, default image | Base for social previews |
verification | Your Google Search Console code | Verifies 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.templateapplies only to child segments, not to the page in the same folder.- You must also set
title.defaultwhen you use a template. - A page that sets
title: 'Services'becomes “Services | Your Brand” automatically. - Use
title.absolutewhen 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:
- Read the slug from
params(it’s a promise in current Next.js versions, so await it). - Fetch the post with the same function the page uses.
- Return the title, description, canonical and Open Graph fields from that data.
- 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.





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.