Add canonical URLs with the Next.js Metadata API

Why this matters

Route-level metadata beats one global tag when URLs multiply.

Before you start

• Next.js App Router project deployed behind a stable canonical host
• A single site URL constant available to metadata exports

How to apply it

1. Set the canonical URL policy

   Choose one absolute form per page: HTTPS, lowercase host and a fixed trailing-slash rule. Store the production origin in a constant such as siteUrl so metadata, links and redirects all read the same value.

   Check: The siteUrl constant resolves to the production origin, and the http, www and apex variants all redirect to it.

2. Keep app/layout.tsx free of a canonical

   Export a metadata object from app/layout.tsx for shared fields only. Do not put a route-specific alternates.canonical there, because every route that forgets to override it inherits the homepage URL.

   Check: grep -n 'alternates' app/layout.tsx shows no route-specific canonical value.

3. Add alternates.canonical per static page

   In each page.tsx export metadata with alternates: { canonical: siteUrl + '/pricing' }. Keep the path lowercase and identical to the deployed route, then rebuild so the tag is rendered in the initial HTML.

   Check: curl -s your production domain/pricing | grep -c 'rel="canonical"' returns 1 and the href equals the pricing URL.

4. Use generateMetadata for dynamic routes

   In app/blog/[slug]/page.tsx await params, load the post and return { alternates: { canonical: siteUrl + '/blog/' + slug } } from generateMetadata so each record gets its own URL instead of the index canonical.

   Check: curl -s your production domain/blog/<slug> | grep -o 'rel="canonical"[^>]*' prints the exact post URL.

5. Remove duplicate sources and confirm

   Delete hardcoded rel=canonical tags in components, CMS widgets and SEO plugins. After deploy, fetch one page per route type, then request validation in the Search Console URL Inspection tool.

   Check: curl -s your production domain/<path> | grep -c 'rel="canonical"' returns 1 for each sampled route.

<goal>
report schema cluster priority anchor snippet metadata crawl metadata page breadcrumb crawl measure anchor.
</goal>

<context>
sitemap heading signal pipeline alt effort heading breadcrumb measure schema content intent query locale.
</context>

<discover_first>
pipeline anchor signal index pipeline sitemap priority sitemap report measure breadcrumb pipeline content content.
</discover_first>

<constraints>
caching query image locale canonical query query caching priority audit audit canonical payload locale.
</constraints>

<plan>
caching content verify pipeline serp route cluster route content locale payload locale pipeline priority.
</plan>

<verify>
verify pipeline metadata crawl cluster index intent link cluster pipeline metadata crawler report page.
</verify>

<report>
measure page canonical image audit section crawler heading page markup heading payload link snippet.
</report>

Source: seo-mcp playbook · curated entry · report an error