---
title: "v4 to v5"
description: "Migrate from Nuxt SEO v4 to v5."
canonical_url: "https://nuxtseo.com/docs/nuxt-seo/migration-guide/v4-to-v5"
last_updated: "2026-09-04T14:14:23.384Z"
---

## 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](/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

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

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

### Set `site.name` explicitly

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

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  site: {
    name: 'My Site',
  },
})
```

### Remove legacy runtime config keys

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

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

### Update server-side APIs

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

## Step 2: Update Content v3 Collections

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

### Replace `asSeoCollection()`{lang="ts"}

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

```diff [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(),
+       }),
+     },
    ),
  },
})
```

::tip
Since you're using the `@nuxtjs/seo` meta-module, you can import all four `defineXxxSchema()`{lang="ts"} functions from `@nuxtjs/seo/content` in a single line, avoiding direct imports from the individual modules:

```ts [content.config.ts]
import { defineOgImageSchema, defineRobotsSchema, defineSchemaOrgSchema, defineSitemapSchema } from '@nuxtjs/seo/content'
```
::

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

```ts [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()`{lang="ts"} functions

The individual module collection wrappers are also deprecated:

| Old                                  | New                                    |
| ------------------------------------ | -------------------------------------- |
| `asSeoCollection()`{lang="ts"}       | Compose individual schemas (see above) |
| `asRobotsCollection()`{lang="ts"}    | `defineRobotsSchema()`{lang="ts"}      |
| `asSitemapCollection()`{lang="ts"}   | `defineSitemapSchema()`{lang="ts"}     |
| `asOgImageCollection()`{lang="ts"}   | `defineOgImageSchema()`{lang="ts"}     |
| `asSchemaOrgCollection()`{lang="ts"} | `defineSchemaOrgSchema()`{lang="ts"}   |

### Ensure correct module order

Load `@nuxtjs/seo` before `@nuxt/content` in your modules array:

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

## Step 3: Update Sitemap Config

### `definePageMeta` sitemap options

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

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

### 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:

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

## 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`