/nuxt-seo

name: nuxt-seo
description: Nuxt SEO v5 modules (robots, sitemap, og-image, schema-org, link-checker, seo-utils, site-config). Use when implementing SEO, robots.txt, sitemaps, Schema.org, or meta tags in Nuxt apps.
license: MIT
metadata:
  version: 4.0.0
  last_updated: 2026-08-03
  module_versions:
    nuxtjs_seo: 5.1.0
    "@nuxtjs/robots": 6.0.6
    "@nuxtjs/sitemap": 8.0.11
    nuxt_og_image: 6.3.1
    nuxt_schema_org: 6.0.4
    nuxt_link_checker: 5.0.6
    nuxt_seo_utils: 8.1.4
    nuxt_site_config: 4.0.7
  nuxt_compatibility: ">=4.0.0"
  auto_trigger_scenarios:
    - Setting up SEO in Nuxt project
    - Configuring robots.txt or sitemap
    - Generating Open Graph images
    - Adding Schema.org structured data
    - Managing meta tags and social sharing
    - Checking and fixing broken links
    - Implementing site-wide SEO configuration
    - Implementing Twitter Cards or Open Graph
    - Setting up canonical URLs
    - Configuring rendering modes (SSR/SSG/ISR)
    - Using IndexNow for instant indexing
    - Implementing rich results with JSON-LD
    - Setting up multilanguage/i18n SEO
    - Configuring SEO route rules
    - Migrating from Nuxt SEO v4 to v5

Nuxt SEO v5

**Status**: Production Ready | **Dependencies**: Nuxt >=4.0.0

Use this skill when building SEO-optimized Nuxt applications with any combination of the 8 official Nuxt SEO modules plus standalone modules.

---

Quick Start (5 Minutes)

1. Install Complete SEO Bundle

# Recommended (v5)
npx nuxt module add @nuxtjs/seo

2. Configure Site Settings

export default defineNuxtConfig({
  modules: ['@nuxtjs/seo'],

  site: {
    url: 'https://example.com',
    name: 'My Awesome Site',
    description: 'Building amazing web experiences',
    defaultLocale: 'en'
  }
})

**CRITICAL (v5 Breaking Change):**

• `site.name` is NO LONGER auto-inferred from `package.json` — set it explicitly
• Set `site.url` to production URL (required for sitemaps and canonical URLs)
• Set `defaultLocale` if using i18n

3. Restart and Verify

Visit these URLs to verify:

• `/robots.txt` - Robots file
• `/sitemap.xml` - Sitemap
• `/__robots__/debug-production.json` - Debug (v5)
• `/__sitemap__/debug-production.json` - Debug (v5)

Individual Module Install

npx nuxt module add @nuxtjs/robots
npx nuxt module add @nuxtjs/sitemap
npx nuxt module add nuxt-og-image

---

Module Overview

| Module | Version | Purpose | |--------|---------|---------| | **@nuxtjs/seo** | v5.1.0 | Primary SEO module (installs all 8 as bundle) | | **@nuxtjs/robots** | v6.0.6 | Manages robots.txt and bot detection | | **@nuxtjs/sitemap** | v8.0.11 | Generates XML sitemaps with advanced features | | **nuxt-og-image** | v6.3.1 | Creates Open Graph images via Vue templates | | **nuxt-schema-org** | v6.0.4 | Builds Schema.org structured data graphs | | **nuxt-link-checker** | v5.0.6 | Finds and fixes broken links with ESLint integration | | **nuxt-seo-utils** | v8.1.4 | SEO utilities, share links, favicons, inline minification | | **nuxt-site-config** | v4.0.7 | Centralized site configuration management |

**Standalone (MIT)**: `nuxt-ai-ready` (llms.txt), `nuxt-skew-protection` (version safety) **Pro (Paid)**: Nuxt SEO Pro — Search Console, Core Web Vitals, MCP server

**For detailed module docs:** Load `references/module-details.md`

---

Critical Rules

Always Do

• Set `site.url` AND `site.name` explicitly in nuxt.config.ts (v5: name no longer auto-inferred)
• Use environment variables for multi-environment setups
• Configure robots.txt to block admin/private pages
• Add Schema.org structured data to all important pages
• Generate OG images for social sharing
• Use `getSiteConfig(event)` on server side (v5: `useSiteConfig(event)` removed)
• Use `defineSitemapSchema()` for Content v3 (v5: `asSitemapCollection()` deprecated)

Never Do

• Forget to set `site.url` and `site.name` (breaks sitemaps, canonical URLs, titles)
• Allow crawling of staging environments
• Use `useSiteConfig(event)` on server side (v5: use `getSiteConfig(event)`)
• Use `asSitemapCollection()` (v5: use `defineSitemapSchema()`)
• Use `getSiteIndexable()` (v5: use `{ indexable } = getSiteConfig(event)`)

---

Known Issues Prevention

Issue #1: Sitemap Not Generating

**Error**: `/sitemap.xml` returns 404 | **Fix**: Set `site.url` in nuxt.config.ts

Issue #2: robots.txt Missing

**Error**: `/robots.txt` not accessible | **Fix**: Install `@nuxtjs/robots` and set `site.url`

Issue #3: OG Images Not Rendering

**Error**: `/__og-image__/og.png` returns error | **Fix**: Use Satori-compatible CSS or switch to Chromium renderer

Issue #4: Schema Validation Errors

**Error**: Invalid JSON-LD | **Fix**: Follow official Schema.org types, validate with Google Rich Results Test

Issue #5: Broken Internal Links

**Error**: 404 on internal links | **Fix**: Enable `nuxt-link-checker` with ESLint rules during development

Issue #6: Duplicate Meta Tags

**Error**: Multiple meta tags with same property | **Fix**: Let modules handle meta tags automatically

Issue #7: Canonical URL Issues

**Error**: Wrong canonical URL | **Fix**: Configure `site.url` and `trailingSlash` correctly

Issue #8: Sitemap Index Errors

**Error**: Sitemap index XML malformed | **Fix**: Use `chunkSize` option to split large sitemaps

Issue #9: Crawling Staging Environment

**Error**: Staging indexed by Google | **Fix**: `disallow: process.env.NUXT_PUBLIC_ENV === 'staging' ? ['/'] : []`

Issue #10: Missing Social Sharing Images

**Error**: No preview on social media | **Fix**: Use `defineOgImage()` on all important pages

Issue #11: Missing Site Name (v5 Breaking)

**Error**: Site title/og:site_name missing | **Fix**: Set `site.name` in nuxt.config.ts or `NUXT_SITE_NAME` env var **Ref**: https://nuxtseo.com/docs/nuxt-seo/migration-guide/v4-to-v5

Issue #12: Server-Side useSiteConfig Error (v5 Breaking)

**Error**: `useSiteCo