← All posts

Next.js SEO: metadata, sitemap and robots in the App Router

How to set titles, canonicals, a sitemap and robots.txt in the Next.js App Router, the three mistakes the defaults make easy, and how to confirm in Search Console that Google sees what you shipped.

QueryScope team · · 8 min read · nextjs seo developers

SEO in the Next.js App Router comes down to four files: a metadata export (or generateMetadata) for titles, descriptions and canonicals, app/sitemap.ts for the sitemap, app/robots.ts for robots.txt, and a root layout that sets metadataBase so relative URLs resolve. Next.js renders all of it into the HTML on the server. What it does not do is stop you shipping a sitemap that changes every URL's date on every build, or a page that quietly loses its Open Graph description. Those are the parts worth getting right.

TL;DR:

  • Set metadataBase and a title.template in app/layout.tsx. Next.js treats a relative URL in metadata without metadataBase as a build error.
  • Give every page its own title, description and alternates.canonical.
  • Metadata objects merge shallowly: a page that sets openGraph replaces the layout's whole openGraph, not one field of it.
  • In app/sitemap.ts, set lastModified from when the content changed. The docs' example uses new Date(), which stamps every URL with the build time.
  • After you ship, check the page in Search Console's URL Inspection, not just in your browser.

Set the defaults once, in the root layout

// app/layout.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  metadataBase: new URL('https://example.com'),
  title: {
    template: '%s | Example',
    default: 'Example',
  },
  description: 'What the site does, in one sentence.',
}

Three things this buys you, all from the generateMetadata reference:

  • metadataBase lets every URL field below it be relative (/pricing, /og.png). Next.js docs: "Using a relative path in a URL-based metadata field without configuring a metadataBase will cause a build error."
  • title.template adds the suffix to every child page's title. It applies to child segments only, and title.default is required alongside it.
  • One place to change. A brand rename touches one file.

Give each page its own title, description and canonical

// app/pricing/page.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'Pricing',            // renders as "Pricing | Example"
  description: 'Plans from $49 a month. Every feature in every plan.',
  alternates: { canonical: '/pricing' },
}

For pages built from data, export generateMetadata instead and read the same record the page renders. Next.js memoizes fetch calls across generateMetadata and the page, so it is one request, not two. You cannot export both metadata and generateMetadata from the same segment, and both only work in Server Components. If the page needs client-side code, keep page.tsx a Server Component and move the interactive part into its own 'use client' file.

Set the canonical explicitly on every page. A page reachable with and without a trailing slash, or with tracking parameters, is several URLs to Google until something says which one counts.

The merge trap: openGraph and robots replace, they do not combine

Next.js merges metadata from the root layout down to the page, and the docs are explicit that the merge is shallow: nested objects such as openGraph and robots "defined in an earlier segment are overwritten by the last segment to define them."

So this layout and page:

// app/layout.tsx
export const metadata = {
  openGraph: { siteName: 'Example', description: 'What the site does.' },
}

// app/blog/page.tsx
export const metadata = {
  openGraph: { title: 'Blog' },
}

produce an Open Graph block with a title and nothing else. The siteName and description are gone, with no warning. The fix from the docs is to keep the shared fields in a plain module and spread them into each page's openGraph.

The same rule applies to robots: a page's robots object replaces the layout's entirely. One copy-pasted robots: { index: false } is all it takes to take a page out of Google, so search the built HTML for noindex before a release.

Try it

Point an SEO agent at your own site, not just an essay about one.

QueryScope holds the plan for your site, reads your real Search Console, and hands the coding agent you already have one change at a time to rank for the searches you decided to win. From $49/month, everything included.

Generate the sitemap, with real dates

app/sitemap.ts returns an array and Next.js serves it at /sitemap.xml:

// app/sitemap.ts
import type { MetadataRoute } from 'next'
import { getAllPosts } from '@/lib/posts'

export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  const posts = await getAllPosts()
  return [
    { url: 'https://example.com', lastModified: '2026-11-01' },
    { url: 'https://example.com/pricing', lastModified: '2026-10-17' },
    ...posts.map((post) => ({
      url: `https://example.com/blog/${post.slug}`,
      lastModified: post.updatedAt, // when the content changed, not when you built
    })),
  ]
}

The sitemap docs use lastModified: new Date() in their example. Copied as is, that tells Google every page on the site changed at the moment of each build. Google reads lastmod only while it keeps matching reality, so a date that moves on every deploy teaches it to ignore your dates. Store the date with the content and pass that through. How Google uses lastmod covers what counts as a change worth a new date.

Two smaller notes. Google ignores changeFrequency and priority, so leave them out. And a single sitemap holds at most 50,000 URLs; past that, Next.js's generateSitemaps splits it into several files.

Generate robots.txt

// app/robots.ts
import type { MetadataRoute } from 'next'

export default function robots(): MetadataRoute.Robots {
  return {
    rules: { userAgent: '*', allow: '/', disallow: '/dashboard/' },
    sitemap: 'https://example.com/sitemap.xml',
  }
}

Block what should never be crawled (an app dashboard, internal search results) and point at the sitemap. Do not use robots.txt to keep a page out of the index: a blocked page can still be indexed from links, without Google ever reading the noindex on it. Use the robots metadata field for that instead.

Both sitemap.ts and robots.ts are cached by default unless they use request-time data, so a sitemap built from a database refreshes on your next build or revalidation, not on every request.

What about metadata on dynamic pages?

For pages rendered per request, Next.js can stream metadata: it sends the page first and appends the tags once generateMetadata resolves. The docs say Google reads streamed metadata correctly because Googlebot runs JavaScript and reads the full page, while crawlers that only read HTML (link previews on social apps, for example) get the metadata in the <head> before the page starts. Prerendered pages do not stream at all, because their metadata is resolved at build time. For most marketing pages and posts, prerendering is the simpler choice anyway.

Check what Google actually sees

The browser shows you your page. Search Console shows you Google's copy of it, and the two drift.

  1. URL Inspection, then "Test live URL". Open the rendered HTML and check the <title>, the description, the canonical and any noindex. Reading URL Inspection explains each field.
  2. The canonical Google chose. URL Inspection shows the canonical you declared and the one Google picked. When they differ, Google has decided another URL is the main version.
  3. The Sitemaps report. Confirm /sitemap.xml was read and how many URLs it found.
  4. Pages not indexed. A new page can sit in "Crawled, currently not indexed" for weeks; three posts on this site have. That is Google's call about the page, not a metadata bug. Finding the pages Google has not indexed covers each status.

Doing this from the repo

Most of this is code, so it belongs where your code lives. SEO tools for developers compares the ones that run in the terminal or the IDE instead of a browser tab. QueryScope is one of them: it connects your own Search Console to your coding agent over MCP, hands the agent one change at a time on the searches you chose, and measures each change from the day Google recrawls the page.

Sources

  • Next.js docs, generateMetadata (metadataBase and the build error without it; title.template and title.default; shallow merging of openGraph and robots; Server Components only; streaming metadata and Googlebot).
  • Next.js docs, sitemap.xml (MetadataRoute.Sitemap; cached by default; generateSitemaps; the new Date() example).
  • Next.js docs, robots.txt (MetadataRoute.Robots; cached by default).
  • Google Search Central, Introduction to robots.txt (a URL blocked by robots.txt can still be indexed from links).
  • Google Search Central, Build and submit a sitemap (Google ignores priority and changefreq; lastmod used when accurate; 50,000 URLs per sitemap).

Try it

Put an SEO agent in your editor.

Ask your coding agent what to work on. QueryScope reads your real Search Console, holds the searches you decided to win, and hands back one move at a time with the proof it worked. From $49/month, everything included. 1, 3 or 10 sites.