v4 to v5 · Nuxt SEO

[NuxtSEO](https://nuxtseo.com/ "Home")

- [Modules](https://nuxtseo.com/docs/nuxt-seo/getting-started/introduction)
- [Tools](https://nuxtseo.com/tools)
- [Pro](https://nuxtseo.com/pro)
- [Learn SEO](https://nuxtseo.com/learn-seo/nuxt) [Releases](https://nuxtseo.com/releases)

[1.4K](https://github.com/harlan-zw/nuxt-seo)

[Nuxt SEO on GitHub](https://github.com/harlan-zw/nuxt-seo)

[User Guides](https://nuxtseo.com/docs/nuxt-seo/getting-started/introduction)

[Releases](https://nuxtseo.com/docs/nuxt-seo/releases/v5)

Nuxt SEO

- [Switch to Nuxt SEO](https://nuxtseo.com/docs/nuxt-seo/getting-started/introduction)
- [Switch to Robots](https://nuxtseo.com/docs/robots/getting-started/introduction)
- [Switch to Sitemap](https://nuxtseo.com/docs/sitemap/getting-started/introduction)
- [Switch to OG Image](https://nuxtseo.com/docs/og-image/getting-started/introduction)
- [Switch to Schema.org](https://nuxtseo.com/docs/schema-org/getting-started/introduction)
- [Switch to Link Checker](https://nuxtseo.com/docs/link-checker/getting-started/introduction)
- [Switch to SEO Utils](https://nuxtseo.com/docs/seo-utils/getting-started/introduction)
- [Switch to Site Config](https://nuxtseo.com/docs/site-config/getting-started/introduction)
- [Switch to Skew Protection](https://nuxtseo.com/docs/skew-protection/getting-started/introduction)
- [Switch to AI Ready](https://nuxtseo.com/docs/ai-ready/getting-started/introduction)

Search…```k`` /`

v5.1.3

- Playgrounds
- [Discord Support](https://discord.com/invite/275MBUBvgP)

### Changelog

### Migration Guides

- [v2 RC to v2 Stable](https://nuxtseo.com/docs/nuxt-seo/migration-guide/rc-to-stable)
- [v2 Beta to v2 RC](https://nuxtseo.com/docs/nuxt-seo/migration-guide/beta-to-rc)
- [Nuxt SEO Kit to Nuxt SEO](https://nuxtseo.com/docs/nuxt-seo/migration-guide/nuxt-seo-kit)
- [v3 to v4](https://nuxtseo.com/docs/nuxt-seo/migration-guide/v3-to-v4)
- [v4 to v5](https://nuxtseo.com/docs/nuxt-seo/migration-guide/v4-to-v5)

### Releases

- [v5.0.0](https://nuxtseo.com/docs/nuxt-seo/releases/v5)

Migration Guides

# v4 to v5

[Copy for LLMs](https://nuxtseo.com/docs/nuxt-seo/migration-guide/v4-to-v5.md)

## [Introduction](#introduction)

Nuxt SEO v5 bumps every sub-module to a new major version (except OG Image, which stays on v6). For the full list of changes, see the [v5 release notes](https://nuxtseo.com/docs/nuxt-seo/releases/v5).

| Module | v4 | v5 |
| --- | --- | --- |
| `nuxt-site-config` | v3 | [**v4**](https://github.com/harlan-zw/nuxt-site-config/releases/tag/v4.0.0) |
| `nuxt-seo-utils` | v7 | [**v8**](https://github.com/harlan-zw/nuxt-seo-utils/releases/tag/v8.0.0) |
| `@nuxtjs/sitemap` | v7 | [**v8**](https://github.com/nuxt-modules/sitemap/releases/tag/v8.0.0) |
| `@nuxtjs/robots` | v5 | [**v6**](https://github.com/nuxt-modules/robots/releases/tag/v6.0.0) |
| `nuxt-schema-org` | v5 | [**v6**](https://github.com/harlan-zw/nuxt-schema-org/releases/tag/v6.0.0) |
| `nuxt-link-checker` | v4 | [**v5**](https://github.com/harlan-zw/nuxt-link-checker/releases/tag/v5.0.0) |
| `nuxt-og-image` | v6 | [v6.2.0](https://github.com/nuxt-modules/og-image/releases/tag/v6.2.0) |

## [Support](#support)

If you get stuck with the migration or have post-migration bugs, please get in touch.

- [Jump in the Discord](https://discord.com/invite/5jDAMswWwX)
- [Make a GitHub issue](https://github.com/harlan-zw/nuxt-seo/issues)

## [Step 1: Update Site Config](#step-1-update-site-config)

Site Config v4 is the most impactful change because every module depends on it.

### [Set `site.name` explicitly](#set-sitename-explicitly)

Site name is no longer inferred from `package.json` or the directory name. Add it to your `nuxt.config`:

```
export default defineNuxtConfig({
  site: {
    name: 'My Site',
  },
})
```

### [Remove legacy runtime config keys](#remove-legacy-runtime-config-keys)

The `siteUrl`, `siteName`, and `siteDescription` runtime config keys are no longer supported. Migrate to the `site` object:

```
export default defineNuxtConfig({
- runtimeConfig: {
-   public: {
-     siteUrl: 'https://example.com',
-     siteName: 'My Site',
-   }
- },
+ site: {
+   url: 'https://example.com',
+   name: 'My Site',
+ },
})
```

### [Update server-side APIs](#update-server-side-apis)

- `useSiteConfig()` → `getSiteConfig(event)`
- `getSiteIndexable()` → `getSiteConfig(event).indexable`
- `SiteConfig` type → `SiteConfigResolved`
- `#internal/nuxt-site-config` import → use named imports from `nuxt-site-config`

## [Step 2: Update Content v3 Collections](#step-2-update-content-v3-collections)

If you use `@nuxt/content` v3, the collection API has changed significantly.

### [Replace `asSeoCollection()`](#replace-asseocollection)

The `asSeoCollection()` wrapper from `@nuxtjs/seo/content` is deprecated. Instead, import each module's `defineXxxSchema()` function and compose them in your collection schema directly.

content.config.ts

```
- import { asSeoCollection } from '@nuxtjs/seo/content'
+ import { defineRobotsSchema } from '@nuxtjs/robots/content'
+ import { defineSitemapSchema } from '@nuxtjs/sitemap/content'
+ import { defineOgImageSchema } from 'nuxt-og-image/content'
+ import { defineSchemaOrgSchema } from 'nuxt-schema-org/content'
+ import { z } from 'zod'

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

You only need to include schemas for the modules you use. For example, if you only use sitemap and robots:

content.config.ts

```
import { defineCollection, defineContentConfig } from '@nuxt/content'
import { defineRobotsSchema } from '@nuxtjs/robots/content'
import { defineSitemapSchema } from '@nuxtjs/sitemap/content'
import { z } from 'zod'

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

### [Replace individual `asXxxCollection()` functions](#replace-individual-asxxxcollection-functions)

The individual module collection wrappers are also deprecated:

| Old | New |
| --- | --- |
| `asSeoCollection()` | Compose individual schemas (see above) |
| `asRobotsCollection()` | `defineRobotsSchema()` |
| `asSitemapCollection()` | `defineSitemapSchema()` |
| `asOgImageCollection()` | `defineOgImageSchema()` |
| `asSchemaOrgCollection()` | `defineSchemaOrgSchema()` |

### [Ensure correct module order](#ensure-correct-module-order)

`@nuxtjs/seo` must be loaded before `@nuxt/content` in your modules array:

nuxt.config.ts

```
export default defineNuxtConfig({
  modules: [
    '@nuxtjs/seo',
    '@nuxt/content', // Must be after @nuxtjs/seo
  ],
})
```

## [Step 3: Update Sitemap Config](#step-3-update-sitemap-config)

### [`definePageMeta` sitemap options](#definepagemeta-sitemap-options)

Sitemap v8 lets you configure sitemap options directly in `definePageMeta`. If you were using route rules or other workarounds for per-page sitemap config, you can simplify:

```
<script setup lang="ts">
definePageMeta({
  sitemap: {
    changefreq: 'daily',
    priority: 0.8,
  },
})
</script>
```

### [i18n multi-sitemap auto-expansion](#i18n-multi-sitemap-auto-expansion)

Custom sitemaps with `includeAppSources: true` are now automatically expanded per locale. You no longer need to manually define a sitemap per locale:

nuxt.config.ts

```
export default defineNuxtConfig({
  sitemap: {
    sitemaps: {
      // Automatically expanded to "en-pages", "fr-pages", etc.
      pages: { includeAppSources: true },
    },
  },
})
```

## [Step 4: Verify](#step-4-verify)

Run your dev server and check for any warnings or errors. The debug production endpoints can help verify configuration:

- Robots: `/__robots__/debug-production.json`
- Sitemap: `/__sitemap__/debug-production.json`
- SEO Utils: `/__nuxt-seo-utils`

[Edit this page](https://github.com/harlan-zw/nuxt-seo/edit/main/docs/content/6.migration-guide/5.v4-to-v5.md)

[Markdown For LLMs](https://nuxtseo.com/docs/nuxt-seo/migration-guide/v4-to-v5.md)

Did this page help you?

[v3 to v4 Migrate from Nuxt SEO v3 to v4.](https://nuxtseo.com/docs/nuxt-seo/migration-guide/v3-to-v4) [v5.0.0 Release notes for Nuxt SEO v5.](https://nuxtseo.com/docs/nuxt-seo/releases/v5)

On this page

- [Introduction](#introduction)
- [Support](#support)
- [Step 1: Update Site Config](#step-1-update-site-config)
- [Step 2: Update Content v3 Collections](#step-2-update-content-v3-collections)
- [Step 3: Update Sitemap Config](#step-3-update-sitemap-config)
- [Step 4: Verify](#step-4-verify)

[GitHub](https://github.com/harlan-zw/nuxt-seo) [ Discord](https://discord.com/invite/275MBUBvgP)

### [NuxtSEO](https://nuxtseo.com/ "Home")

- [Getting Started](https://nuxtseo.com/docs/nuxt-seo/getting-started/introduction)
- [MCP](https://nuxtseo.com/docs/nuxt-seo/guides/mcp)

Modules

- [Robots](https://nuxtseo.com/docs/robots/getting-started/introduction)
- [Sitemap](https://nuxtseo.com/docs/sitemap/getting-started/introduction)
- [OG Image](https://nuxtseo.com/docs/og-image/getting-started/introduction)
- [Schema.org](https://nuxtseo.com/docs/schema-org/getting-started/introduction)
- [Link Checker](https://nuxtseo.com/docs/link-checker/getting-started/introduction)
- [SEO Utils](https://nuxtseo.com/docs/seo-utils/getting-started/introduction)
- [Site Config](https://nuxtseo.com/docs/site-config/getting-started/introduction)
- [Skew Protection](https://nuxtseo.com/docs/skew-protection/getting-started/introduction)
- [AI Ready](https://nuxtseo.com/docs/ai-ready/getting-started/introduction)

### [NuxtSEO Pro](https://nuxtseo.com/pro "Nuxt SEO Pro")

- [Getting Started](https://nuxtseo.com/pro)
- [Dashboard](https://nuxtseo.com/pro/dashboard)
- [Pro MCP](https://nuxtseo.com/pro/docs/getting-started/mcp-setup)

### [Learn SEO](https://nuxtseo.com/learn-seo "Learn SEO")

Nuxt

- [Mastering Meta](https://nuxtseo.com/learn-seo/nuxt/mastering-meta)
- [Controlling Crawlers](https://nuxtseo.com/learn-seo/nuxt/controlling-crawlers)
- [Launch & Listen](https://nuxtseo.com/learn-seo/nuxt/launch-and-listen)
- [Routes & Rendering](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering)
- [Staying Secure](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering/security)

Vue

- [Vue SEO Guide](https://nuxtseo.com/learn-seo/vue)
- [Mastering Meta](https://nuxtseo.com/learn-seo/vue/mastering-meta)
- [Controlling Crawlers](https://nuxtseo.com/learn-seo/vue/controlling-crawlers)
- [SPA SEO](https://nuxtseo.com/learn-seo/vue/spa)
- [SSR Frameworks](https://nuxtseo.com/learn-seo/vue/ssr-frameworks)
- [SEO Checklist](https://nuxtseo.com/learn-seo/checklist)
- [Pre-Launch Warmup](https://nuxtseo.com/learn-seo/pre-launch-warmup)
- [Backlinks & Authority](https://nuxtseo.com/learn-seo/backlinks)

### [Tools](https://nuxtseo.com/tools "SEO Tools")

- [Social Share Debugger](https://nuxtseo.com/tools/social-share-debugger)
- [Robots.txt Generator](https://nuxtseo.com/tools/robots-txt-generator)
- [Meta Tag Checker](https://nuxtseo.com/tools/meta-tag-checker)
- [HTML to Markdown](https://nuxtseo.com/tools/html-to-markdown)
- [XML Sitemap Validator](https://nuxtseo.com/tools/xml-sitemap-validator)
- [Schema.org Validator](https://nuxtseo.com/tools/schema-validator)
- [Keyword Idea Generator](https://nuxtseo.com/tools/keyword-generator)
- [Keyword Research](https://nuxtseo.com/tools/keyword-research)
- [SERP Analyzer](https://nuxtseo.com/tools/serp-analyzer)
- [Domain Rankings](https://nuxtseo.com/tools/domain-rankings)

Copyright © 2023-2026 Harlan Wilton - [MIT License](https://github.com/harlan-zw/nuxt-seo/blob/main/license) · [mdream](https://mdream.dev)