/nuxtjs-seo

@nuxtjs/seo

Requires Nuxt ^4.6.1 || ^5.0.0 and Node ^22.22.3 || ^24.15.0 || >=26.0.0. Nuxt installs declared moduleDependencies and checks versions.

In human dev, the first home response checks fixes, tips, and modules. Required findings report once per Nitro server instance; agent/CI skip terminal checks; production registers none. Locale prefixes and app base paths work.

Only required setup affects warnings and completion; DevTools shows tips separately. Tips use resolved defaults and app config for opt-in features, excluding inline minification and general SEO advice. Opt-outs suppress tips; unavailable data waits for retry.

Tips report weekly per project. State is .nuxt/cache/nuxt-seo/setup-tips.json; deleting resets it. nuxtseo: { tips: false } disables tips, not required checks. Healthy projects without tips report nothing.

Options, composables, and components come from submodules. Docs: nuxtseo.com/docs/nuxt-seo. This Skill covers bundle additions; use each module's Skill or docs below.

Setup

npx nuxt module add seo

export default defineNuxtConfig({
  modules: ['@nuxtjs/seo'],
  site: { url: 'https://example.com', name: 'My Site' },
})

• Add only @nuxtjs/seo to modules; Nuxt installs submodules once.
• Set site.url and site.name; v5 stopped inferring them from package.json.
• Set NUXT_APP_SECRET in production; see the NUXT_APP_SECRET trap.
• If the app needs OG images, install a renderer: npx nuxt-og-image enable takumi. See the renderer traps.

Automatic behaviour

With site.url and site.name, production, for example, adds allowing /robots.txt, sitemap, and per-page robots meta; static routes in /sitemap.xml; title, canonical, and page Open Graph metadata; WebSite/WebPage JSON-LD; /llms.txt and Markdown pages; retained assets with app-manifest polling. Dev robots disallows all. Link checks run only on prerender.

Option ownership

The meta module owns only nuxtseo.enabled and nuxtseo.tips:

• site: nuxt-site-config (skilld.dev/gh/harlan-zw/nuxt-site-config)
• robots: @nuxtjs/robots (nuxtseo.com/docs/robots)
• sitemap: @nuxtjs/sitemap (nuxtseo.com/docs/sitemap)
• ogImage: nuxt-og-image (nuxtseo.com/docs/og-image)
• schemaOrg: nuxt-schema-org (skilld.dev/gh/harlan-zw/nuxt-schema-org)
• seo: nuxt-seo-utils (skilld.dev/gh/harlan-zw/nuxt-seo-utils)
• linkChecker: nuxt-link-checker (skilld.dev/gh/harlan-zw/nuxt-link-checker)
• aiReady: nuxt-ai-ready (nuxtseo.com/docs/ai-ready)
• skewProtection: nuxt-skew-protection (nuxtseo.com/docs/skew-protection)

seo configures nuxt-seo-utils, not the bundle. nuxtseo: false or nuxtseo: { enabled: false } installs no submodule.

Disable a submodule

false skips setup; enabled: false registers nothing. Both remove the module's routes, tags, and output:

export default defineNuxtConfig({
  modules: ['@nuxtjs/seo'],
  site: { url: 'https://example.com', name: 'My Site' },
  ogImage: false,
  linkChecker: { enabled: false },
})

You cannot disable site; other submodules need it. To drop the bundle, set nuxtseo: false or remove it from modules. A submodule you list still installs.

AI Ready and Skew Protection

Both install automatically. On v5 upgrade, remove duplicate modules entries; keep their options.

• AI Ready serves Markdown and llms.txt; prerendering adds llms-full.txt. It publishes project/layer Agent Skills at public/skills/<name>/SKILL.md, not root skills/; MCP plus site URL generates an API catalog. Databases, background indexing, and cron are opt-in. Set either aiReady.agentSkills or aiReady.apiCatalog to false.
• The bundle sets Skew Protection updateStrategy: 'polling' and cookie: false; site options win. Preserve node_modules/.cache/nuxt-seo/skew-protection in CI or set skewProtection.storage. Handlers using isClientOutdated need a skewProtection.cookie config object.
• Set aiReady: false or skewProtection: false to disable either module.

Nuxt Content v3

Import four helpers from @nuxtjs/seo/content. With pnpm, @nuxtjs/robots/content fails ERR_MODULE_NOT_FOUND because submodules are not top-level dependencies. Add zod 4; helpers use it as an optional peer.

import { defineCollection, defineContentConfig } from '@nuxt/content'
import { defineOgImageSchema, defineRobotsSchema, defineSchemaOrgSchema, defineSitemapSchema } from '@nuxtjs/seo/content'
import { z } from 'zod'

export default defineContentConfig({
  collections: { content: defineCollection({
    type: 'page',
    source: '**/*.md',
    schema: z.object({
      robots: defineRobotsSchema(),
      sitemap: defineSitemapSchema(),
      ogImage: defineOgImageSchema(),
      schemaOrg: defineSchemaOrgSchema(),
    }),
  }) },
})

schemaOrg and sitemap apply without page code. robots needs page.seo passed to useSeoMeta():

<script setup lang="ts">
const { data: page } = await useAsyncData('page', () => queryCollection('content').path(useRoute().path).first())
useSeoMeta(page.value?.seo || {})
</script>

@nuxtjs/seo and @nuxt/content order does not change output. v6 removes asSeoCollection(): replace defineCollection(asSeoCollection({ ... })) with the schema above.

Traps

• Production OG images return 500 without NUXT_APP_SECRET. Only /_og/ fails; pages render. Dev creates a temporary secret, builds do not. Run npx nuxt-og-image generate-secret; set a 32+ character production secret. Static and ogImage: { zeroRuntime: true } need none.
• Fresh install has no OG images without a template or renderer. Run npx nuxt-og-image enable takumi, or set ogImage: false.
• A template renderer is missing. Interactive nuxt dev asks to install it. CI and Agent shells log npx nypm add, never edit package.json; production build then fails if used.
• An app submodule replaces the bundled copy. An old pin stops build; upgrade or remove it.
• @nuxtjs/i18n below v10 fails every build. Upgrade i18n.
• Content robots: 'noindex' stays in the sitemap. Only robots: false removes it; both render noindex, nofollow.

Version limits

• Nuxt ^4.6.1 || ^5.0.0; older versions stop build. Run npx nuxt upgrade. Nuxt 3 stays on v5.
• Nuxt Content v2 is not supported; use Content v3 with Zod 4.
• v6 moves every submodule up one major and bundles AI Ready and Skew Protection. Migration: nuxtseo.com/docs/nuxt-seo/migration-guide/v5-to-v6
• For bundled modules, pins, NUXT_APP_SECRET, DevTools, and nuxtseo: false, use the instructions above.
• robots:* and sitemap:* contexts use RequestEvent: replace ctx.event.node.req.headers.authorization with ctx.event.req.headers.get('authorization').
• #internal/nuxt-robots, bare #schema-org, bare #seo-utils: use #robots/server, #schema-org/app, #seo-utils/app.
• On a submodule version error, run pnpm why <package> to find the older pin.

Debug

• Run npx nuxt dev, open home. Terminal lists setup and tips; Agent and CI skip it.
• Dev /__nuxt-seo__/setup.json returns module/setup data. Other data: /__site-config__/debug.json, /__robots__/debug.json, /__sitemap__/debug.json, /_og/debug.json.
• DevTools needs nuxtseo-devtools-host, or shows an install button. npx nuxt info lists versions.