nextjs-seo

---

name: nextjs-seo description: Next.js App Router SEO optimization and auditing. Use when implementing or fixing SEO in a Next.js app — metadata and generateMetadata, viewport/themeColor, Open Graph and og/twitter images (file conventions + ImageResponse), web app manifest, favicons/icons, sitemap.xml, robots.txt, canonical URLs, hreflang/i18n alternates, JSON-LD structured data and rich results, Core Web Vitals (LCP/INP/CLS), AI search/GEO and AI crawler rules (GPTBot, OAI-SearchBot), or diagnosing Google indexing problems (Search Console, "Discovered/Crawled - currently not indexed"). Also use to run an SEO audit checklist. Not for general Next.js feature work unrelated to SEO.

Next.js SEO Optimization

Start with evidence and useful content

Read the installed Next.js version and relevant node_modules/next/dist/docs/ guides before changing framework code; use current official docs when local docs are unavailable. Use Vercel MCP documentation search for platform behavior when available, but check retrieved examples against the installed framework. Do not copy a legacy cache API from a search snippet into a newer app.

• Solve the reader's task first. A short useful page does not need padding. Give the H1, subtitle and section headings distinct jobs; do not repeat the same phrase in each for SEO. Keep UI copy concise, concrete and useful.
• Do not add generic introductions, keyword blocks, decorative badges, a FAQ or TL;DR just to make a page look optimized. Add content only when it answers a real question. Preserve necessary explanations and disclosures.
• Create team, location or category pages only when each offers distinct, maintainable value. A swapped name/logo and duplicate list is insufficient.
• Describe seasons, availability and update times from current data. Do not leave pre-launch copy on an active service or change timestamps for freshness.
• Separate evidence: a Search Console performance export shows queries and traffic, not indexing status, Google's canonical choice or CWV. Use the relevant report or URL Inspection; mark unavailable checks as unverified.
• Report findings and verification before predicting impact. No ranking, indexing, rich-result or AI-citation guarantees.

Quick SEO Audit

Run this checklist for any Next.js project:

1. Check robots.txt: curl https://your-site.com/robots.txt
2. Check sitemap: curl https://your-site.com/sitemap.xml
3. Check metadata: View page source, search for <title> and <meta name="description">
4. Check JSON-LD: View page source, search for application/ld+json
5. Check Core Web Vitals: Use PageSpeed Insights (pagespeed.web.dev) and the Search Console CWV report for field data — Lighthouse is lab-only and can't measure INP

Essential Files

app/layout.tsx - Root Metadata

import type { Metadata, Viewport } from 'next';

// Viewport must be a separate export. `themeColor`, `colorScheme` and
// `viewport` inside `metadata` are dropped: Next.js 16 emits no tag, only an
// "Unsupported metadata" build warning.
export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  maximumScale: 5,
  userScalable: true,
  themeColor: [
    { media: '(prefers-color-scheme: light)', color: '#ffffff' },
    { media: '(prefers-color-scheme: dark)', color: '#0a0a0a' },
  ],
};

export const metadata: Metadata = {
  metadataBase: new URL('https://your-site.com'),
  title: {
    default: 'Site Title - Main Keyword',
    template: '%s | Site Name',
  },
  // ~150-160 chars is a guideline, not a limit — Google truncates per device/query
  description: 'Compelling description with target keywords',
  // No `keywords` field: Google ignores the keywords meta tag entirely
  openGraph: {
    type: 'website',
    locale: 'en_US',
    url: 'https://your-site.com',
    siteName: 'Site Name',
    title: 'Site Title',
    description: 'Description for social sharing',
    images: [{ url: '/og-image.png', width: 1200, height: 630, alt: 'Site preview' }],
  },
  twitter: {
    card: 'summary_large_image',
    title: 'Site Title',
    description: 'Description for Twitter',
    images: ['/og-image.png'],
  },
  // Set alternates.canonical per page; a root '/' would be inherited by children.
  robots: {
    index: true,
    follow: true,
  },
};

app/sitemap.ts - Dynamic Sitemap

import type { MetadataRoute } from 'next';

export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  const baseUrl = 'https://your-site.com';
  const posts = await getPosts(); // your CMS/DB

  return [
    {
      url: baseUrl,
      images: [`${baseUrl}/og-image.png`], // Image Sitemap entry
    },
    { url: `${baseUrl}/about` },
    ...posts.map((post) => ({
      url: `${baseUrl}/blog/${post.slug}`,
      lastModified: post.updatedAt, // real content timestamp
    })),
  ];
}

lastModified must reflect the content's actual last change (CMS updatedAt, file mtime, git commit date) — Google uses lastmod only when it's consistently accurate, and new Date() on every build marks everything "just changed", which teaches Google to ignore it. Skip changeFrequency and priority: Google ignores both.

app/robots.ts - Robots Configuration

import type { MetadataRoute } from 'next';

export default function robots(): MetadataRoute.Robots {
  const baseUrl = 'https://your-site.com';

  return {
    rules: [
      {
        userAgent: '*',
        allow: '/',
        disallow: ['/api/', '/admin/'],
        // Never disallow /_next/: crawlers need render-critical CSS/JS.
        // A named group (Googlebot, OAI-SearchBot…) ignores these rules; see mistake 11.
      },
    ],
    sitemap: `${baseUrl}/sitemap.xml`,
  };
}

host was omitted intentionally — it's a non-standard directive Google ignores. Use canonical URLs / 301s to declare the preferred host instead. See references/sitemap-robots.md.

app/manifest.ts - Web App Manifest

Same MetadataRoute family as sitemap/robots, placed at the root of app/. Not an SEO requirement — a PWA-completeness nicety with no ranking effect; skip it unless the site is (or may become) a PWA. Full example in references/metadata-api.md.

OG / Twitter Images

Three ways to set social images — prefer the file conventions over hand-syncing URLs in the metadata object:

1. External URL in metadata (the openGraph.images / twitter.images examples above) — fine for externally hosted images.
2. Static file convention (recommended default): drop opengraph-image.(jpg|jpeg|png|gif) and/or twitter-image.* into a route segment (app/opengraph-image.png for the root, app/blog/opengraph-image.png for /blog). Next.js auto-emits og:image/twitter:image + :type/:width/:height. A deeper, more specific image overrides one above it. Add alt text with a sibling opengraph-image.alt.txt. Build fails if the file exceeds 8 MB (OG) / 5 MB (Twitter).
3. Dynamic generation with ImageResponse (per-page/per-post images): an opengraph-image.tsx in the route segment exporting alt, size, contentType and a default Image({ params }) (params is a Promise in v16) that returns new ImageResponse(<jsx/>, { ...size }). Renders via Satori — flexbox only, no display: grid, 500 KB bundle cap (JSX, fonts, images), fonts ttf/otf/woff only; statically optimized at build time unless it reads request-time data. Full example, fonts, generateImageMetadata and the favicon/icon.tsx/apple-icon conventions: references/metadata-api.md.

Key Principles

Cache Components & SEO

With cacheComponents: true, use "use cache" for data/components that can be shared and whose freshness requirements permit caching. Static content needs no extra cache directive merely for SEO:

// app/(home)/sections/hero-section.tsx
import { cacheLife, cacheTag } from "next/cache";

export async function HeroSection() {
  "use cache";
  cacheLife("hours");   // SEO content that changes a few times/day; see profiles below
  cacheTag("hero");     // Invalidate via updateTag("hero") in a Server Action

  const data = await fetchData();
  return <div>{/* SEO-visible content */}</div>;
}

Choose cacheLife from the product's freshness requirements and the installed Next.js documentation. Do not infer a cache lifetime from the page category; marketing and legal pages also need timely publication and invalidation.

Key rules:

• "use cache" must be the first statement in the function body (or at the top of the file for file-level caching)
• No cookies()/headers()/runtime searchParams inside a plain "use cache" scope. Keep public content separate from personalized data; do not accidentally cache private information for all users. Check the installed docs before using experimental private caching.
• Invalidate with updateTag("hero") inside a Server Action (read-your-writes; it throws outside one), or revalidateTag("hero", "max") from a Route Handler / webhook (the one-argument form is deprecated)
• Route segment exports revalidate, dynamic and fetchCache error with Cache Components enabled; without it, follow the installed version's cache model. Verify next build, the served content and publish-time invalidation.
• A database read does not by itself make a sitemap update after deployment. Configure and verify its refresh/invalidation path. Metadata can be static or runtime-dependent; inspect the route rather than assuming.

Rendering Strategy for SEO

Strategy	Use When	SEO Impact
"use cache"	Shared data with a defined refresh policy	Can include content in the prerendered shell
SSG (Static)	Content known at build time	Content available in HTML; plan updates
SSR	Content needed at request time	Content available in the response; measure latency
CSR	Interactive or authenticated features	Avoid relying on browser-only fetching for critical public content

These are rendering trade-offs, not ranking tiers. A Client Component can still be server-prerendered; "use client" does not mean its content is absent from HTML.

Core Web Vitals Targets

Metric	Target	Impact
LCP (Largest Contentful Paint)	≤ 2.5s	Loading speed
INP (Interaction to Next Paint)	≤ 200ms	Interactivity
CLS (Cumulative Layout Shift)	≤ 0.1	Visual stability

• Use the 75th percentile of field measurements, segmented by device. Evaluate each metric separately; this does not mean the same 75% of visits pass all three simultaneously. Lighthouse is a lab diagnostic, not an INP field score.
• Good CWV does not guarantee ranking. Relevant content, crawlability and accurate metadata remain necessary; avoid invented numerical ranking weights.
• Keep mobile content, metadata and structured data equivalent to desktop. Verify authorship and credentials rather than generating them.

References

• Metadata API — references/metadata-api.md: read when writing generateMetadata, OG/icon files, ImageResponse, the manifest, or when streaming metadata / htmlLimitedBots is in play
• Sitemap & Robots — references/sitemap-robots.md: read for generateSitemaps, image/video sitemaps, multi-group robots rules, static robots.txt/sitemap.xml files
• JSON-LD Structured Data — references/json-ld.md: read before adding any schema type; has the supported/deprecated rich-result list and the @graph pattern
• AI Search (GEO/AEO) & AI Crawlers — references/ai-search.md: read when deciding robots rules for GPTBot/OAI-SearchBot/ClaudeBot etc., or when asked about llms.txt or AI Overviews
• SEO Audit Checklist — references/checklist.md: read when asked to audit a site end to end
• Troubleshooting — references/troubleshooting.md: read when a page is missing from Google, stuck in "Discovered/Crawled – currently not indexed", or indexes fine but never hydrates

Common Mistakes to Avoid

1. Mixing next-seo with Metadata API - Use only Metadata API in App Router
2. Missing canonical URLs - Set a self-referencing alternates.canonical when duplicate/parameterized URLs are a risk; it's a hint, not a requirement — Google may pick its own canonical
3. Using CSR for SEO pages - Use SSG/SSR for indexable content
4. Blocking /_next/ in robots.txt - Crawlers need render-critical CSS/JS; never disallow /_next/
5. Missing metadataBase - Not a build error: relative OG/Twitter image URLs fall back to the Vercel deployment URL or http://localhost:3000 with only a warning, and relative canonical/hreflang URLs stay relative (Google requires absolute hreflang URLs)
6. Viewport in metadata - themeColor/colorScheme/viewport in metadata are ignored; use export const viewport
7. Mixing metadata object and generateMetadata - Use one or the other in the same route segment
8. Duplicating icons in metadata + file conventions - Prefer favicon.ico/icon.*/opengraph-image.* file conventions; they auto-emit tags and override the metadata object
9. Blanket-blocking AI crawlers - GPTBot disallow: / blocks training but leaves you in AI search; don't accidentally block search bots (OAI-SearchBot, Claude-SearchBot, PerplexityBot). See references/ai-search.md
10. Adding the keywords meta tag for Google - Google ignores it entirely (no indexing or ranking effect); it's noise, not a signal
11. Assuming named robots.txt groups inherit * rules - Per RFC 9309 §2.2.1 the * group applies only when no group matches, and Google never merges a specific group with *. A { userAgent: 'OAI-SearchBot', allow: '/' } group drops the wildcard's /api///admin/ disallows — repeat them in every named group
12. Trusting browser view for bot metadata - Check status, headers and the complete production response for Googlebot and a relevant HTML-limited bot. Streaming may place metadata outside the initial head. A spoofed User-Agent tests response behavior, not Google's actual crawl access or indexing; use URL Inspection and verified bot logs where available.
13. Assuming a route that indexes well also works - A PPR route (◐ in the build output) can serve perfect SEO HTML while none of its <Suspense> boundaries hydrate on a direct load. Load the route directly in a browser and interact with it; the observation and the check are in references/troubleshooting.md.

Quick Fixes

Add noindex to a page

export const metadata: Metadata = {
  robots: {
    index: false,
    follow: true,
  },
};

Keep the page crawlable for noindex to be seen. Robots disallow is not an index-removal or access-control mechanism. Preview protection and noindex are separate concerns; see references/sitemap-robots.md.

Dynamic metadata per page

type Props = { params: Promise<{ id: string }> };

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { id } = await params;            // params is a Promise in current Next.js
  const product = await getProduct(id);
  return {
    title: product.name,
    description: product.description,
  };
}

Canonical for dynamic routes

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

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { slug } = await params;
  return {
    alternates: {
      canonical: `/products/${slug}`,
    },
  };
}