Nextjs Seo

1---2name: nextjs-seo3description: Next.js SEO optimization guide. Use when building Next.js apps, optimizing for search engines, fixing Google indexing issues, implementing metadata, sitemaps, robots.txt, JSON-LD, or auditing SEO.4argument-hint: "[question or URL]"5---6 7# Next.js SEO Optimization8 9Comprehensive SEO guide for Next.js 16+ applications using App Router.10 11> Next.js 16+ App Router (latest stable)12 13## Quick SEO Audit14 15Run this checklist for any Next.js project:16 171. **Check robots.txt**: `curl https://your-site.com/robots.txt`182. **Check sitemap**: `curl https://your-site.com/sitemap.xml`193. **Check metadata**: View page source, search for `<title>` and `<meta name="description">`204. **Check JSON-LD**: View page source, search for `application/ld+json`215. **Check Core Web Vitals**: Run Lighthouse in Chrome DevTools22 23## Essential Files24 25### app/layout.tsx - Root Metadata26 27```typescript28import type { Metadata, Viewport } from 'next';29 30// Viewport (separate export required in Next.js 14+).31// `themeColor`, `colorScheme`, and `viewport` inside the `metadata` object32// are deprecated since Next.js 13.2.0 — they must be exported via `viewport`.33export const viewport: Viewport = {34  width: 'device-width',35  initialScale: 1,36  maximumScale: 5,37  userScalable: true,38  themeColor: [39    { media: '(prefers-color-scheme: light)', color: '#ffffff' },40    { media: '(prefers-color-scheme: dark)', color: '#0a0a0a' },41  ],42};43 44export const metadata: Metadata = {45  metadataBase: new URL('https://your-site.com'),46  title: {47    default: 'Site Title - Main Keyword',48    template: '%s | Site Name',49  },50  description: 'Compelling description with keywords (150-160 chars; Google typically displays this range)',51  keywords: ['keyword1', 'keyword2', 'keyword3'],52  openGraph: {53    type: 'website',54    locale: 'en_US',55    url: 'https://your-site.com',56    siteName: 'Site Name',57    title: 'Site Title',58    description: 'Description for social sharing',59    images: [{ url: '/og-image.png', width: 1200, height: 630, alt: 'Site preview' }],60  },61  twitter: {62    card: 'summary_large_image',63    title: 'Site Title',64    description: 'Description for Twitter',65    images: ['/og-image.png'],66  },67  alternates: {68    canonical: '/',69  },70  robots: {71    index: true,72    follow: true,73  },74};75```76 77### app/sitemap.ts - Dynamic Sitemap78 79```typescript80import type { MetadataRoute } from 'next';81 82export default function sitemap(): MetadataRoute.Sitemap {83  const baseUrl = 'https://your-site.com';84 85  return [86    {87      url: baseUrl,88      lastModified: new Date(),89      changeFrequency: 'weekly',90      priority: 1,91      images: [`${baseUrl}/og-image.png`], // Next.js 16 Image Sitemap92    },93    {94      url: `${baseUrl}/about`,95      lastModified: new Date(),96      changeFrequency: 'monthly',97      priority: 0.8,98    },99  ];100}101```102 103### app/robots.ts - Robots Configuration104 105```typescript106import type { MetadataRoute } from 'next';107 108export default function robots(): MetadataRoute.Robots {109  const baseUrl = 'https://your-site.com';110 111  return {112    rules: [113      {114        userAgent: '*',115        allow: '/',116        disallow: ['/api/', '/admin/'],117        // Do NOT disallow /_next/ — crawlers need render-critical CSS/JS118        // Do NOT add bot-specific rules (Googlebot, Bingbot) unless overriding wildcard119      },120    ],121    sitemap: `${baseUrl}/sitemap.xml`,122    host: baseUrl,123  };124}125```126 127## Key Principles128 129### Cache Components & SEO (Next.js 16+)130 131With `cacheComponents: true` in next.config.ts, use the `"use cache"` directive for SEO-critical server components:132 133```typescript134// app/(home)/sections/hero-section.tsx135export async function HeroSection() {136  "use cache";137  cacheLife("minutes");   // Built-in profile: ~15 min138  cacheTag("hero");       // For targeted invalidation via revalidateTag("hero")139 140  const data = await fetchData();141  return <div>{/* SEO-visible content */}</div>;142}143```144 145**Key rules:**146- `"use cache"` must be the first statement in the function body147- No `cookies()`/`headers()` inside cache scope148- Use `cacheLife()` + `cacheTag()` instead of `export const revalidate`149- Sitemaps and metadata are static by default — only use `"use cache"` if they fetch dynamic data150 151### Rendering Strategy for SEO152 153| Strategy | Use When | SEO Impact |154|----------|----------|------------|155| "use cache" | Server components with periodic data | Best - cached HTML, fast TTFB |156| SSG (Static) | Content rarely changes | Best - pre-rendered HTML |157| SSR | Dynamic content per request | Great - server-rendered |158| CSR | Dashboards, authenticated areas | Poor - avoid for SEO pages |159 160### Core Web Vitals Targets161 162| Metric | Target | Impact |163|--------|--------|--------|164| LCP (Largest Contentful Paint) | < 2.5s | Loading speed |165| INP (Interaction to Next Paint) | < 200ms | Interactivity |166| CLS (Cumulative Layout Shift) | < 0.1 | Visual stability |167 168## References169 170- **Metadata API**: See [references/metadata-api.md](references/metadata-api.md)171- **Sitemap & Robots**: See [references/sitemap-robots.md](references/sitemap-robots.md)172- **JSON-LD Structured Data**: See [references/json-ld.md](references/json-ld.md)173- **SEO Audit Checklist**: See [references/checklist.md](references/checklist.md)174- **Troubleshooting**: See [references/troubleshooting.md](references/troubleshooting.md)175 176## Common Mistakes to Avoid177 1781. **Mixing next-seo with Metadata API** - Use only Metadata API in App Router1792. **Missing canonical URLs** - Always set `alternates.canonical`1803. **Using CSR for SEO pages** - Use SSG/SSR for indexable content1814. **Blocking `/_next/` in robots.txt** - Crawlers need render-critical CSS/JS; never disallow `/_next/`1825. **Missing metadataBase** - Required for relative URLs in metadata1836. **Viewport in metadata** - Must be separate export in Next.js 14+1847. **Mixing metadata object and generateMetadata** - Use one or the other, not both185 186## Quick Fixes187 188### Add noindex to a page189 190```typescript191export const metadata: Metadata = {192  robots: {193    index: false,194    follow: false,195  },196};197```198 199### Dynamic metadata per page200 201```typescript202type Props = { params: Promise<{ id: string }> };203 204export async function generateMetadata({ params }: Props): Promise<Metadata> {205  const { id } = await params;            // params is a Promise in Next.js 15+206  const product = await getProduct(id);207  return {208    title: product.name,209    description: product.description,210  };211}212```213 214### Canonical for dynamic routes215 216```typescript217type Props = { params: Promise<{ slug: string }> };218 219export async function generateMetadata({ params }: Props): Promise<Metadata> {220  const { slug } = await params;221  return {222    alternates: {223      canonical: `/products/${slug}`,224    },225  };226}227```