How to Set a Canonical URL in Next.js (App Router)

Quick answer: how do I set a canonical URL in Next.js?

In the App Router, set the canonical URL with the `alternates.canonical` field of the Metadata object, then set `metadataBase` in the root layout so relative canonical paths resolve to your production host. Use a static `metadata` export for fixed pages and `generateMetadata` for dynamic routes.

import type { Metadata } from "next";

export const metadata: Metadata = {
  title: "Pricing",
  alternates: {
    canonical: "/pricing",
  },
};

Why canonical URLs matter

A canonical URL tells search engines which URL is the preferred version of a page when the same or similar content is reachable from multiple URLs. Without it, duplicate URLs from query parameters, trailing slashes, or www and apex hosts can split ranking signals or let Google pick the wrong canonical.

• Consolidate duplicate or near-duplicate URLs to one preferred URL.
• Avoid query-parameter and trailing-slash duplicates competing in search.
• Keep the canonical aligned with the URL you actually want indexed.

Set metadataBase so relative canonicals resolve

When canonical and Open Graph URLs use relative paths, set `metadataBase` in the root layout to your canonical production host. Next.js then resolves relative `alternates.canonical` and `openGraph.url` values into absolute URLs.

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

export const metadata: Metadata = {
  metadataBase: new URL("https://example.com"),
  alternates: {
    canonical: "/",
  },
};

Canonical URLs for dynamic routes

For dynamic segments such as app/blog/[slug]/page.tsx, build the canonical inside `generateMetadata` from the route params so every page gets its own canonical URL instead of a shared one.

import type { Metadata } from "next";

type PageProps = {
  params: Promise<{ slug: string }>;
};

export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
  const { slug } = await params;

  return {
    alternates: {
      canonical: "/blog/" + slug,
    },
  };
}

Canonical URLs for pagination and query parameters

Filters, sorting, and tracking parameters create many URLs for one logical page. Point the canonical at the clean URL so search engines consolidate them, unless a paginated page is genuinely a distinct indexable page.

• Drop tracking parameters such as utm_source from the canonical.
• For filtered lists, canonicalize to the unfiltered page when the content is essentially the same.
• Keep page 2 and beyond self-canonical only when each page should be indexed independently.

Common Next.js canonical URL mistakes

Most canonical issues come from drift between the canonical, the Open Graph URL, and the real indexable route, or from host and slash inconsistencies.

• Canonical drift: `alternates.canonical` and `openGraph.url` pointing at different URLs.
• Mixing www and apex, or http and https, in the canonical host.
• Trailing-slash mismatch between the canonical and the route Next.js actually serves.
• Reusing one canonical across every dynamic route instead of per-page values.
• Setting a canonical to a noindex or redirected URL.

Verify the canonical URL

After deploying, confirm the rendered canonical link tag matches the URL you want indexed, then validate it in Google Search Console.

• View source and check the canonical link tag in the document head.
• Use the URL Inspection tool to see the Google-selected canonical.
• Confirm the canonical returns HTTP 200 and is not blocked by robots.

Generate canonical metadata quickly

Use the Next Metadata Generator to produce a typed App Router starter with the canonical URL, Open Graph URL, and Twitter fields aligned, then paste it into the route and adjust per-page values.

Next.js canonical URL scenarios

Use FrameworkKit to generate the starter code, then review the output before shipping it in production.

Next Metadata resources

FAQ

Related tools