Next.js SEO

TL;DR — Next.js is one of the best frameworks for SEO when you use it right. Build your pages on the server or at build time (not entirely in the browser), set a unique title, description, and canonical on every page, and use the built-in next/image and next/link components. Next.js gives you all the tools — but it won’t write your SEO tags for you.

What Next.js SEO is

Next.js is a popular framework built on React for making websites and web apps. Because it’s React under the hood, a lot of the page can be built with JavaScript — and that’s where SEO questions come in. Next.js SEO is just the practice of making sure search engines can crawl, render, and index a Next.js site, and using the framework’s built-in features to do that well.

The good news: Next.js can build your pages ahead of time or on the server, so search engines get the finished HTML right away. That avoids the biggest risk with JavaScript sites — content that only shows up after scripts run. (For the broader picture, see JavaScript SEO.)

The one big decision: where the page gets built

When someone — or Googlebot — asks for a page, where does the finished HTML come from? Next.js gives you a few options:

• At build time (Static / SSG) — the page is built into a plain HTML file ahead of time. Fast, and search engines get everything immediately.
• On the server, per request (SSR) — the server builds the full page each time. Also search-friendly, and always fresh.
• A mix (ISR) — static pages that refresh on a timer. A good default for most content.
• In the browser (Client-Side / CSR) — the server sends a near-empty shell and JavaScript fills it in. This is the risky one for SEO; avoid it for your main content.

The modern App Router uses Server Components by default, which means your content ends up in the HTML automatically — a great starting point for SEO.

The simple checklist

• Give every page a unique title and description.
• Set a canonical URL on every page.
• Use the next/image component for images (it stops the page from jumping around as images load, and makes them smaller).
• Use next/link for internal links (it creates real links Google can follow).
• Don’t put your main content behind client-side rendering.
• Create a sitemap and a robots.txt (Next.js has simple file-based ways to do both). Evidence for this claim Next.js App Router supports special metadata files for sitemap and robots output. Scope: Next.js App Router file conventions. Confidence: high · Verified: 2026-07-14 Next.js: Metadata files

The thing people get wrong

“Next.js handles SEO automatically.” It doesn’t — not the parts that matter. Next.js gives you the machinery (a metadata system, sitemap and robots conventions, an image component), but you still have to write your titles, descriptions, and canonicals yourself. Evidence for this claim Next.js provides metadata APIs, but developers supply page-specific metadata values. Scope: Next.js App Router metadata and generateMetadata APIs. Confidence: high · Verified: 2026-07-14 Next.js: Metadata and OG images Every page needs its own. A site where every page shares one title, or has no canonical, is the most common way a Next.js build underperforms.

Want the deeper version — the two routers, the Metadata API, metadataBase, the LCP image trick, and the mistakes that quietly break indexing? Switch to the Advanced tab.

TL;DR — Next.js solves the hardest JavaScript SEO problems by default when you use it right. The App Router defaults to Server Components and supports SSG/SSR/ISR — all of which ship rendered HTML, so there’s no render-queue delay. Set metadata with the native Metadata API (metadata / generateMetadata), and remember metadataBase or your canonicals and OG images go relative. Use app/sitemap.ts and app/robots.ts, pre-build dynamic routes with generateStaticParams, set priority on the LCP image, and keep links as real next/link anchors. The Pages Router is also SEO-capable via next/head. The failures are predictable — and most of them aren’t Next.js’s fault, they’re yours.

Where Next.js fits

Next.js is a React framework, so everything in JavaScript SEO applies. What makes it worth its own guide is that Next.js ships first-class answers to most JS-SEO problems: server rendering, static generation, a metadata system, and sitemap/robots conventions. The hard part isn’t whether Google can read it — Google has rendered JavaScript for years — it’s choosing the right rendering mode and not leaving the SEO basics unwired. This is a specialized case of headless CMS SEO: the CMS barely matters, the frontend’s rendering decisions decide everything.

One framing to keep straight: “this is a Next.js site” doesn’t tell you how any single URL is delivered. Rendering mode, caching, and Server/Client Component boundaries are set per route (sometimes per segment) — a project can mix a static marketing page, an SSR product page, and a Client Component dashboard. Don’t extrapolate one route’s behavior to “the whole app”; test the specific URL.

Two routers, two sets of mechanics

Next.js has two routers, and they handle SEO differently:

• Pages Router (the older model) — data fetching via getStaticProps / getServerSideProps; metadata via <Head> from next/head (or the next-seo package); no Server Components.
• App Router (v13+, the current and recommended approach) — React Server Components by default; the native Metadata API (metadata export / generateMetadata); file conventions for app/sitemap.ts and app/robots.ts; generateStaticParams for dynamic routes. Evidence for this claim The App Router uses Server Components and supports generateStaticParams plus metadata file conventions. Scope: Current Next.js App Router behavior; route rendering can become dynamic based on APIs used. Confidence: high · Verified: 2026-07-14 Next.js: Server and Client Components Next.js: generateStaticParams

Both can rank well. The App Router gives you a cleaner, integrated metadata system (no next/head juggling) and Server Components out of the box, which is why I’d reach for it on a new build. But “App Router or you can’t do SEO” is a myth — plenty of Pages Router sites rank fine.

Rendering modes and what each means for SEO

How Google handles JavaScript is a three-phase pipeline — crawl, then a deferred render wave, then index. “All pages with a 200 HTTP status code are sent to the rendering queue.” The whole game in Next.js is choosing a mode that puts your content in the HTML before that render wave, so there’s nothing to wait for. Evidence for this claim Google crawls, renders, and indexes JavaScript pages, and successful pages can enter the rendering queue. Scope: Google Search processing, not a promise that a URL will be indexed. Confidence: high · Verified: 2026-07-14 Google: JavaScript SEO basics

• Static Site Generation (SSG) — pages pre-rendered at build time. HTML is immediately available with no render-queue risk. Best for content that doesn’t change every minute. generateStaticParams() (App Router) / getStaticPaths() (Pages Router) decides which dynamic routes get pre-built.
• Incremental Static Regeneration (ISR) — static pages that revalidate after a set interval (export const revalidate = 3600). Crawlers get static HTML with low TTFB and the content stays fresh. A strong default — with one trap: after the window expires the next request (possibly Googlebot) still gets the stale page; the fresh version serves on the request after that. For genuinely volatile data (prices, stock), SSR is safer.
• Server-Side Rendering (SSR) — HTML rendered per request. Crawlers get fully rendered HTML immediately; the tradeoff is server latency, so watch TTFB and LCP. export const dynamic = 'force-dynamic' or using request-time APIs (cookies, headers) opts a route into SSR.
• React Server Components (App Router default) — render on the server and send HTML; no JavaScript ships for the component itself. Content is in the initial response with no hydration gap. This is the best default for SEO. Interactivity lives in Client Components marked 'use client'.
• Client-Side Rendering (CSR) — rendered entirely in the browser. Googlebot can index it after the render wave (median ~10 seconds, but the 90th percentile stretches to hours), and other crawlers — Bingbot, AI bots, social preview bots — may get an empty page. In the App Router, CSR is opt-in ('use client'); in the Pages Router, avoid fetching primary content in useEffect. Don’t use it for content you want ranked.

A reminder I keep coming back to: “Googlebot can render it” is not the same as “you should make Googlebot render it.” Rendering is expensive, deferred, and not universal across crawlers.

The Metadata API (App Router)

The Metadata API is Server Component only — metadata resolves on the server before the page renders, so it lands in the initial HTML. Export metadata from layout.js or page.js:

export const metadata: Metadata = {
  title: 'My Page',
  description: 'Page description',
}

Or, when the tags depend on fetched data, use generateMetadata():

export async function generateMetadata({ params }) {
  const post = await getPost(params.slug)
  return { title: post.title, description: post.description }
}

The fields that matter for SEO:

• title — supports a string, a template ('%s | Brand'), a default, and an absolute override. Set the template once in the root layout and per-page titles inherit it.
• description, alternates.canonical (the correct way to set a canonical in the App Router), openGraph (images must resolve to absolute URLs), twitter (also used by LinkedIn and Slack previews), and robots (index/follow plus googleBot-specific directives like max-snippet, max-image-preview).
• metadataBase — required for canonical and OG image URLs to resolve correctly. Forgetting it is the single most common Next.js metadata bug: relative URLs leak into your canonical and Open Graph tags, breaking social previews and muddying canonical signals.

A title-template example:

// app/layout.tsx
export const metadata: Metadata = {
  metadataBase: new URL('https://example.com'),
  title: { template: '%s | Brand Name', default: 'Brand Name' },
}
// app/blog/page.tsx
export const metadata: Metadata = { title: 'My Blog Post' }
// Output: <title>My Blog Post | Brand Name</title>

Two gotchas. First, metadata is shallowly merged from layout to page — a nested object like openGraph defined in a child segment replaces the parent’s entirely, so a page-level openGraph: { title: 'Home' } quietly drops any openGraph.images set in the layout. Second — and this one bites people — metadata only works in Server Components. Export it from a 'use client' file and it silently does nothing.

Streaming metadata. For dynamically rendered pages, generateMetadata can stream the metadata after the initial HTML. Googlebot executes JavaScript and inspects the full DOM, so streamed metadata works for Google. But Next.js detects “HTML-limited bots” — Bingbot, Twitterbot, Slackbot, facebookexternalhit — and ships them blocking metadata in the <head> instead. Per the Next.js docs, “streaming metadata is disabled for bots and crawlers that expect metadata to be in the <head> tag.” This is automatic; no configuration needed. It’s a detail almost no competing guide covers, and it’s why streaming metadata isn’t a risk for the bots that can’t wait for it. Prerendered pages are a different case entirely — metadata there resolves at build time, so there’s no stream to worry about. This behavior is version-specific (current as of Next.js 16.2.10); re-check the generateMetadata docs when you upgrade. And because delivery paths differ by entry point, verify metadata two ways, not one: a direct/production request (curl -I or View Source) and a client-side navigation to the same route — the head can update differently between the two.

Metadata with next/head (Pages Router)

On the Pages Router, metadata lives in <Head> from next/head:

import Head from 'next/head'

export default function Page() {
  return (
    <>
      <Head>
        <title>My Page | Brand</title>
        <meta name="description" content="Description" />
        <link rel="canonical" href="https://example.com/my-page" />
      </Head>
      {/* page content */}
    </>
  )
}

Set title and description per page (not just in _app.js), and put a canonical on every page including paginated variants. The next-seo package standardizes this with a <NextSeo> component and structured-data helpers. Migrating to the App Router mostly means trading next/head and next-seo for the native metadata export.

Do you need the next-seo package? It’s a third-party plugin (not part of Next.js itself) — actively maintained, at v7.2.0 as of this writing, not archived. Its own docs are explicit about where it fits: for standard meta tags on the App Router, the package’s README recommends using Next.js’s built-in generateMetadata/metadata export instead of <NextSeo>; on the Pages Router, <NextSeo> is still a reasonable convenience layer over next/head. The one App Router use case the package still covers is its JSON-LD helper components (ArticleJsonLd, FAQPageJsonLd, etc. with useAppDir), which some teams prefer over hand-rolling <script type="application/ld+json">. Bottom line: on a new App Router build, reach for the native Metadata API first — the package is optional, not a requirement, and its own maintainers say so.

Sitemaps

In the App Router, app/sitemap.ts is a file convention that outputs /sitemap.xml:

import type { MetadataRoute } from 'next'

export default function sitemap(): MetadataRoute.Sitemap {
  return [
    { url: 'https://acme.com', lastModified: new Date(), priority: 1 },
    { url: 'https://acme.com/blog', lastModified: new Date(), priority: 0.8 },
  ]
}

For large sites, generateSitemaps() shards into multiple files (Google’s limit is 50,000 URLs per sitemap), each served at /.../sitemap/[id].xml. The sitemap output also supports image sitemaps, video sitemaps, and localized alternates.languages. On the Pages Router, use next-sitemap or generate pages/sitemap.xml.js with getServerSideProps.

robots.txt

app/robots.ts generates your robots file programmatically:

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

Per-user-agent rules and multiple sitemaps are supported. The Pages Router uses a static public/robots.txt. The rule you cannot get wrong on either router: never disallow your JavaScript or CSS — Google won’t render from blocked files, and on a JS framework that can blank out the page entirely.

next/image and Core Web Vitals

next/image is one of the strongest reasons to use the framework for SEO. It lazy-loads below-the-fold images, requires width/height (or fill) so it reserves space and prevents layout shift / CLS, serves WebP/AVIF automatically, and emits a proper srcset from the sizes prop. The single most important CWV optimization is the priority prop on your hero / above-the-fold image, which preloads it for a faster LCP:

<Image src="/hero.jpg" width={1200} height={630} priority alt="Hero" />

Forgetting priority on the LCP image is the most common Next.js CWV mistake — and CWV problems are widespread on real Next.js sites (see the Stats tab for the Salt Agency data). alt is required: empty for decorative images, descriptive for content images.

next/link and internal linking

next/link renders standard <a href> anchors in the HTML, so Google follows them normally, and it adds client-side navigation plus background prefetching of in-viewport links in production. The SEO rule is simple: use next/link for internal links, and never substitute an onClick handler or JavaScript navigation that doesn’t produce a real anchor — those links aren’t crawlable. Use prefetch={false} on low-value links to save bandwidth if you need to.

Dynamic routes and generateStaticParams

generateStaticParams() tells Next.js which dynamic routes to pre-render at build time:

// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
  const posts = await getPosts()
  return posts.map((post) => ({ slug: post.slug }))
}

Pages built this way are fully static HTML — best for SEO. Without it, dynamic routes are rendered on-demand (SSR) by default, which is fine but reintroduces server latency. Combine it with revalidate (ISR) for content that updates regularly. Make sure all important dynamic URLs are in generateStaticParams so nothing waits on the render queue.

Structured data (JSON-LD)

The Metadata API has no structured-data field — you inject JSON-LD as a <script> in a Server Component, which keeps it in the server-rendered HTML at zero client-bundle cost:

const jsonLd = { '@context': 'https://schema.org', '@type': 'Article', /* … */ }
return <script type="application/ld+json"
  dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />

Article/BlogPosting, BreadcrumbList, Product, and FAQPage are the usual types. Validate with the Rich Results Test after any rendering change.

Common Next.js SEO mistakes

Drawn from real audits and the patterns above:

1. Missing or relative canonicals — often from a forgotten metadataBase, which also breaks OG image URLs.
2. No priority on the LCP image — the biggest CWV miss.
3. 404 views returning 200 — use the built-in notFound() to return a real status; soft 404s are rampant on Next.js sites.
4. metadata exported from a Client Component — silently does nothing; it’s Server Component only.
5. CSR for primary content — fetching critical content in useEffect means non-Google crawlers get empty pages.
6. Hash (#) routing instead of the History API — those views aren’t separately crawlable.
7. Not exporting generateStaticParams — dynamic routes render on-demand instead of being pre-built.
8. openGraph overwritten by layout inheritance — child segments replace, not merge.
9. Blocking JS/CSS in robots.txt or via a Content Security Policy that stops Googlebot’s headless Chrome from loading scripts — test with URL Inspection.

Deployment notes

Next.js is built by Vercel; hosting there gives tight integration (edge CDN for static and ISR pages, good TTFB) but isn’t required. Define permanent redirects in redirects() in next.config.js (returns 308, or 301 with permanent: true) for reliable signaling to crawlers, set security and caching headers via headers(), and use X-Robots-Tag response headers for path-based noindex rules when per-page robots metadata is awkward.

What to check where. Cache state, status codes, redirects, and streamed metadata don’t all show up in the same test — a route can look fine in one check and still be broken in another:

None of this is guaranteed by the framework — Next.js gives you the mechanisms (redirects(), notFound(), revalidation, streaming), but cache keys, invalidation, preview state, and deployment configuration are still your responsibility to get right and to test in production, not just locally.

One last note on dynamic rendering — serving prerendered HTML to bots and JavaScript to users. Google has deprecated it as a recommendation: “dynamic rendering was a workaround and not a long-term solution.” You don’t need it on Next.js anyway — SSR, SSG, ISR, and Server Components all put content in the HTML natively. Mention it so you recognize it in an audit; don’t build on it.

The happy path: App Router + Server Components + ISR + the Metadata API (with metadataBase) + next/image with priority. Get those right and most of Next.js SEO is handled.

AI summary

A condensed take on the Advanced version:

• Next.js solves most JS-SEO problems by default — if you pick the right rendering mode and wire up the basics. The framework gives you infrastructure; it writes none of your tags.
• Two routers: App Router (v13+, recommended) uses Server Components and the native Metadata API; Pages Router uses next/head / next-seo. Both can rank.
• Rendering modes: SSG and Server Components are the best default (content in the HTML, no render-queue delay). ISR is a strong middle ground but has a stale-on-first-request-after-revalidation trap. SSR for volatile data. CSR is risky — non-Google crawlers may get an empty page.
• Metadata API (App Router): metadata export or generateMetadata(), Server Component only. metadataBase is required or canonicals and OG images go relative. openGraph in a child segment replaces the parent’s; metadata in a 'use client' file does nothing.
• Streaming metadata works for Google but Next.js ships blocking metadata to HTML-limited bots (Bingbot, Twitterbot, Slackbot, facebookexternalhit) automatically.
• File conventions: app/sitemap.ts (with generateSitemaps() for 50k+ URLs) and app/robots.ts. Never block .js/.css.
• next/image prevents CLS, serves WebP/AVIF; set priority on the LCP image — the top CWV win. next/link renders real crawlable <a href> anchors and prefetches.
• generateStaticParams pre-builds dynamic routes; without it they render on-demand.
• JSON-LD is injected as a <script> in a Server Component (no Metadata API field).
• The next-seo package is optional, not required. It’s actively maintained third-party software (v7.2.0, not archived), and its own docs recommend the built-in generateMetadata/metadata export for App Router meta tags — <NextSeo> remains useful mainly on the Pages Router, or for its JSON-LD helper components.
• Rendering mode is set per route, not per project — don’t assume one URL’s behavior from another’s; test the specific route (direct request and client navigation both).
• Top mistakes: missing metadataBase, no LCP priority, 404s returning 200 (use notFound()), metadata in a Client Component, CSR primary content.
• Dynamic rendering is deprecated — you don’t need it; SSR/SSG/ISR/Server Components cover it.

Official documentation

Primary-source documentation from Next.js and the search engines.

Next.js

• Metadata and OG Images — the App Router metadata system, metadataBase, and OG image generation.
• generateMetadata API Reference — static metadata vs. generateMetadata, streaming metadata, and the HTML-limited bots list.
• sitemap.xml File Convention — app/sitemap.ts, generateSitemaps(), image/video/localized sitemaps.
• robots.txt File Convention — app/robots.ts, per-user-agent rules, and multiple sitemaps.
• Learn: SEO — Next.js’s own SEO learning path (introductory; partly predates the App Router).

Google

• Understand JavaScript SEO Basics — the crawl → render → index pipeline, the 200-status rendering queue, soft 404s in SPAs, canonicals, and the History API.
• Dynamic Rendering (deprecated workaround) — why Google deprecated it and what to use instead (SSR, static rendering, hydration).
• In-Depth Guide to How Google Search Works — where rendering sits in crawl → index → serve.

Bing / Microsoft

• IndexNow / indexnow.org — the push protocol to wire to a Next.js publish/revalidation event.

Quotes from the source

On-the-record statements from Google, Next.js, and Google reps. Each link is a deep link that jumps to the quoted passage on the source page.

Google — how JavaScript pages are processed

• “All pages with a 200 HTTP status code are sent to the rendering queue, no matter whether JavaScript is present on the page.” — Google Search Central docs. Jump to quote

Google — dynamic rendering is deprecated

• “Dynamic rendering was a workaround and not a long-term solution for problems with JavaScript-generated content in search engines.” — Google Search Central docs. Jump to quote
• “…creates additional complexities and resource requirements.” — Google Search Central docs. Jump to quote

Next.js — streaming metadata and HTML-limited bots

• “Streaming metadata is disabled for bots and crawlers that expect metadata to be in the <head> tag (e.g. Twitterbot, Slackbot, Bingbot).” — Next.js docs, generateMetadata. Jump to quote

John Mueller, Google (via Search Engine Journal coverage)

• On the growing role of JavaScript in SEO: “You’re going to run into significantly more JavaScript over the next years than in the 2-ish decades in SEO before. If you’re keen on technical SEO, then past HTML you’re going to need to understand JS more and more.” Read the coverage

Next.js SEO checklist

A quick pass to confirm a Next.js site is crawlable, indexable, and fast:

• Primary content renders in HTML on first request (Server Components / SSG / SSR / ISR) — not only after client-side JavaScript.
• No important page depends on CSR for its main content.
• Every page has a unique title and description (use a title template in the root layout).
• metadataBase is set in the root layout (App Router) so canonicals and OG images are absolute.
• A canonical is set per page via alternates.canonical (App Router) or <link rel="canonical"> (Pages Router) — not a single shared homepage canonical.
• metadata is exported only from Server Components, never a 'use client' file.
• generateStaticParams covers all important dynamic routes.
• app/sitemap.ts (or next-sitemap) outputs a current sitemap; generateSitemaps() shards sites over 50k URLs.
• app/robots.ts / public/robots.txt exists and does not block .js or .css.
• Images use next/image with width/height or fill; the LCP image has priority; all have alt.
• Internal links use next/link (real <a href>) — no onClick-only navigation.
• 404 views call notFound() and return a real 404 (no soft 404s).
• JSON-LD is injected in a Server Component <head>/body and passes the Rich Results Test.
• Permanent redirects live in redirects() in next.config.js (308 / permanent).

The mental models

1. Rendering mode is the product. Before debugging anything in a Next.js site, answer one question: how is this route rendered? Server Components / SSG / SSR / ISR put content in the HTML and are low-risk; CSR is the risky one. Almost every Next.js SEO problem resolves to this.

2. The framework gives infrastructure, not content. Next.js ships the Metadata API, sitemap/robots conventions, and the Image component — but it writes none of your titles, descriptions, canonicals, or structured data. “Next.js handles SEO automatically” is the most expensive myth here.

3. One source of truth for URLs. Set metadataBase once and build canonicals, OG images, and sitemap entries from it (absolute, never relative). One base URL kills the relative-canonical and broken-OG-image class of bugs.

4. Server Components first, Client Components only where needed. Default to Server Components so content and metadata land in the HTML. Reach for 'use client' only for interactivity — and remember metadata can’t come from a Client Component.

5. The decision rule for rendering. Mostly static (blogs, docs, marketing) → SSG (or ISR on a timer). Always-fresh / volatile (prices, stock) → SSR. Changes hourly/daily, want static speed → ISR (mind the stale-first-request trap). Interactive, behind a login, not indexed → CSR is fine. Public content you want ranked → never CSR.

Next.js SEO — cheat sheet

Rendering modes

App Router vs Pages Router

Fast rules

• Set metadataBase or canonicals/OG images go relative.
• metadata is Server Component only — 'use client' exports do nothing.
• Child-segment openGraph replaces the parent’s (no merge).
• priority on the LCP image = the top CWV win.
• Internal links = next/link (real <a href>); no onClick-only nav.
• 404 → call notFound() (real 404, not soft 404).
• Never disallow .js / .css.
• Streaming metadata → blocking for Bingbot, Twitterbot, Slackbot, facebookexternalhit.
• Dynamic rendering: deprecated — use SSR / SSG / ISR / Server Components.

Quick checks for a Next.js build

A few command-line checks before you reach for a full crawler.

Is your content in the raw HTML (or only after JS runs)?

macOS / Linux:

# Raw HTML as the server sends it — the "first fetch", before any client JS
curl -sL -A "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)" \
  https://example.com/page/ -o raw.html

# Is your headline actually in the raw HTML? (empty result = CSR / JS-dependent)
grep -o "Your headline text" raw.html

# Did metadataBase do its job? Canonical and OG URLs should be absolute, not relative
grep -iE 'rel="canonical"|og:(url|image)' raw.html

Windows (PowerShell):

$ua = "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)"
Invoke-WebRequest -Uri "https://example.com/page/" -UserAgent $ua -OutFile raw.html
Select-String -Path raw.html -Pattern "Your headline text"
Select-String -Path raw.html -Pattern 'rel="canonical"','og:url','og:image'

If the headline is missing from raw.html but shows in your browser, that route is client-rendered. If canonicals or OG image URLs come out relative, you’ve forgotten metadataBase.

Confirm you aren’t blocking JS/CSS (including the Next.js _next directory)

macOS / Linux:

curl -sL https://example.com/robots.txt | \
  grep -iE "disallow.*\.(js|css)|Disallow:\s*/_next"

Windows (PowerShell):

(Invoke-WebRequest "https://example.com/robots.txt").Content |
  Select-String -Pattern "Disallow.*\.(js|css)","Disallow:\s*/_next"

Any match here is almost always a mistake — Google won’t render from blocked files. A plain curl can’t run JavaScript, so for the rendered DOM use URL Inspection’s “View Crawled Page → rendered HTML.”

Tools for auditing a Next.js site

• URL Inspection (Google Search Console) — the source of truth. Run a live test, then view the rendered HTML, screenshot, and page resources (what loaded vs. what was blocked) to catch CSR gaps and blocked _next resources.
• Rich Results Test — confirm JSON-LD made it into the rendered output after any rendering change.
• Lighthouse / Chrome DevTools — measure LCP, CLS, and INP; check whether your hero image is preloaded (priority).
• Ahrefs Site Audit — crawls with JavaScript rendering, surfacing missing/relative canonicals, broken metadata, redirect chains, and indexability issues across the frontend.
• Screaming Frog SEO Spider — crawl with JS rendering on/off to diff raw vs. rendered HTML, and build pre/post crawl comparisons for migrations.
• Bing Webmaster Tools — Bing’s URL Inspection and where IndexNow submissions appear.

Mistakes to avoid on Next.js

Concrete patterns that quietly break SEO on real Next.js builds — prevent these before they ship, rather than debugging them after a traffic drop.

Shipping without metadataBase in the root layout

Why it’s wrong: without metadataBase, alternates.canonical and openGraph.images resolve to relative paths instead of absolute URLs. A relative canonical can confuse canonicalization signals, and relative OG image URLs break link previews on social and messaging apps.

What to do instead: set metadataBase: new URL('https://example.com') once in app/layout.tsx and let every page inherit it. Check it with grep -iE 'rel="canonical"|og:(url|image)' against a raw HTML fetch — the URLs should start with https://.

Overwriting a layout’s openGraph from a child segment

Why it’s wrong: metadata merges shallowly from layout to page. A page-level openGraph: { title: 'Home' } doesn’t merge with the layout’s openGraph.images — it replaces the whole object, silently dropping the images.

What to do instead: either repeat the full openGraph object (images included) at every level that overrides it, or only override the specific top-level metadata fields you actually need to change, and leave openGraph untouched where the layout’s default is fine.

Exporting metadata from a Client Component

Why it’s wrong: the Metadata API is Server Component only. Add 'use client' to a file that also exports metadata and the export does nothing — no error, no warning, just a page with no title or description.

What to do instead: keep metadata / generateMetadata exports in a plain Server Component file (page.tsx or layout.tsx without 'use client'). If a page needs client interactivity, put that in a separate child component and import it — don’t add 'use client' to the file that owns the metadata export.

Fetching primary content in useEffect (or relying on full CSR)

Why it’s wrong: content rendered only in the browser isn’t in the initial HTML. Google will eventually render it, but the median render delay is real and the 90th percentile stretches to hours — and non-Google crawlers (Bing, social preview bots, most AI crawlers) often don’t render JavaScript at all, so they see an empty page.

What to do instead: default to Server Components, SSG, ISR, or SSR for anything you want indexed. Reserve 'use client' and useEffect data-fetching for interactive UI that doesn’t need to be crawlable — a filter widget, not the article body.

Returning 200 for a “not found” view

Why it’s wrong: rendering a “not found” message without calling notFound() returns a normal 200 status. That’s a soft 404 — Google can index the empty-content page instead of recognizing it as missing, and soft 404s are one of the most common real-world Next.js SEO problems.

What to do instead: call the built-in notFound() function so the route returns a real 404. Confirm with curl -I on a known-missing URL and check the status code directly, not just what renders in the browser.

Skipping generateStaticParams on important dynamic routes

Why it’s wrong: without it, dynamic routes fall back to on-demand rendering (SSR), which still works for SEO but adds server latency to every first request for that URL — including Googlebot’s.

What to do instead: enumerate the URLs that matter (product pages, blog posts, category pages) in generateStaticParams() so they’re pre-built, and pair it with revalidate (ISR) for content that changes after launch.

Test yourself: Next.js SEO

Five quick questions on making a Next.js site crawlable, indexable, and fast. Pick an answer for each, then check.

Resources worth your time

My related writing

• JavaScript SEO: A Definitive Guide — my full guide to rendering, DOM parity, canonicals in JS, sitemaps, and the rendering-mode trade-offs that Next.js sits on top of. This Next.js guide is the framework-specific layer on top of it.
• The Beginner’s Guide to Technical SEO — where rendering and crawling fit in the bigger picture.

My speaking

• JavaScript SEO — Ungagged 2019 (SlideShare) — my walkthrough of how frameworks separate frontend from backend and how Googlebot renders. (Standing disclaimer: the dynamic-rendering recommendation in that deck is now outdated — Google deprecated it.)

From around the industry

• Metadata and OG Images (Next.js docs) — the App Router metadata system, metadataBase, and OG image generation.
• generateMetadata API Reference (Next.js docs) — static vs. dynamic metadata and the HTML-limited bots / streaming-metadata behavior.
• sitemap.xml File Convention (Next.js docs) — app/sitemap.ts, generateSitemaps(), and localized/image sitemaps.
• Common SEO Issues on Next.js Websites (Salt Agency) — a 50-site audit study with real data on soft 404s and LCP failures.
• How Google Handles JavaScript Throughout the Indexing Process (Vercel) — render-timing data from nextjs.org’s own server beacons.
• The Complete Next.js SEO Guide (Strapi) — a thorough framework-walkthrough covering rendering modes, metadata, and structured data.
• App Router vs Pages Router for SEO (Wisp) — a focused comparison of the two routers from an SEO angle.
• r/TechSEO — the community for rendering/indexing debugging.

Stats worth citing

• Render timing is usually fast, occasionally very slow. Vercel’s analysis of 37,000+ server-beacon pairs on nextjs.org found a median render time of ~10 seconds, but a 90th percentile of ~3 hours and a 99th percentile of ~18 hours — which is exactly why you don’t want primary content waiting on the render queue. Source
• CWV and soft 404s are widespread on real Next.js sites. Salt Agency’s audit of 50 Next.js sites found 41/50 returning soft 404s (404 views at a 200 status) and only 3/50 passing LCP thresholds — a reminder that the framework’s CWV advantages only help if you use next/image with priority and return real status codes. Source

Next.js SEO

Next.js SEO is the set of practices and built-in features that make a Next.js site crawlable, indexable, and rankable — rendering mode (SSG/SSR/ISR/Server Components), the App Router Metadata API, sitemap.ts/robots.ts conventions, next/image, and next/link.

Related: JavaScript SEO, Headless CMS SEO

Next.js SEO

Next.js SEO refers to the practices, configurations, and framework features used to make a website built with Next.js — a React-based full-stack framework — easily crawlable, indexable, and rankable by search engines. Because Next.js supports multiple rendering modes (SSG, SSR, ISR, and React Server Components), it inherits both the benefits and the risks of JavaScript-heavy architectures, while shipping first-class APIs for metadata, sitemaps, robots.txt, and image optimization that make technical SEO far easier than on a bare React single-page app.

Next.js has two routers with different SEO mechanics. The older Pages Router uses getStaticProps/getServerSideProps and manages metadata through next/head (or the next-seo package). The current App Router (v13+) defaults to React Server Components and provides a native Metadata API — the metadata export or the generateMetadata() function — that resolves on the server so tags appear in the initial HTML. The App Router also adds file conventions like app/sitemap.ts and app/robots.ts, plus generateStaticParams() for pre-building dynamic routes.

The biggest wins come from using the framework as intended: Server Components and SSG/ISR put content in the HTML so there is no rendering-queue delay, next/image prevents layout shift and serves modern formats, and next/link renders real crawlable anchors. The most common mistakes are a missing metadataBase (which breaks canonical and Open Graph URLs), no priority on the LCP image, exporting metadata from a Client Component (where it does nothing), and 404 views that return a 200 status.

Related: JavaScript SEO, Headless CMS SEO

Changelog