Nuxt SEO Kit to Nuxt SEO

Support

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

• Jump in the Discord
• Make a GitHub issue
• Provide feedback

Module Rename

With v2 the module name and scope is clarified with the rename to Nuxt SEO.

• 1.* - Nuxt SEO Kit nuxt-seo-kit (Nuxt Layer)
• 2.x - Nuxt SEO @nuxtjs/seo (Nuxt Module)

The v2 allows you to use all SEO modules at runtime, prerendering is no longer required. It also comes with improved i18n compatibility.

It has been renamed to provide a better base for growing out the Nuxt SEO ecosystem as well as to make the layer -> module change more obvious.

# remove nuxt-seo-kit
pnpm remove nuxt-seo-kit && pnpm i -D @nuxtjs/seo

yarn remove nuxt-seo-kit && yarn add -D @nuxtjs/seo

npm remove nuxt-seo-kit && npm install -D @nuxtjs/seo

export default defineNuxtConfig({
-  extends: ['nuxt-seo-kit'],
  modules: [
+  '@nuxtjs/seo',
  ]
})

Breaking Changes

<SeoKit>, useSeoKit() removed: these APIs set up all the default meta and module configuration for you.

In v2, they are no longer needed as functionality has been moved to a plugin.

<template>
-  <SeoKit />
</template>

<script setup>
-  useSeoKit()
</script>

If you'd like to opt-out of the these v2 configurations, you can set automaticDefaults to false.

Site Config Changes

In v1, site config was set through runtime config. In v2, we have a dedicated module with helpers for handling this config called nuxt-site-config.

The move to a module is to allow greater flexibility in changing site configuration at runtime.

If you were specifying any static config in runtimeConfig previously, it's now recommended to move this to the site key.

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      // you can remove environment variables, they'll be set automatically
      siteUrl: process.env.NUXT_PUBLIC_SITE_URL,
      siteName: 'My App'
    }
  }
})

export default defineNuxtConfig({
  site: {
    name: 'My App'
  }
})

When updating your config:

• All keys are without the site prefix
• The language config has been renamed to defaultLocale

The behavior for environment variables hasn't changed. It's recommended to read how site config works for more advanced configuration.

Prerendering Changes

In v1, you had to prerender all pages, and we modified your nuxt.config to ensure this happened.

In v2, the server can generate everything at runtime, and we no longer provide the prerendering changes.

If you'd like to keep the prerendering changes, you can add this to your nuxt.config.

export default defineNuxtConfig({
  nitro: {
    prerender: {
      crawlLinks: true,
      routes: [
        '/',
      ],
    },
  },
})

Module Upgrades

Nuxt Robots

Upgraded from v1 to v3:

• v2 release notes
• v3 release notes

No breaking changes.

Nuxt Sitemap

Upgraded from v1 to v3:

• v2 release notes
• v3 release notes

No breaking changes.

Nuxt Schema.org

Upgraded from v2 to v3:

• v3 release notes

No breaking changes.

Nuxt OG Image

Upgraded from v1 to v2:

• v2 release notes

We removed the following options from nuxt.config ogImage:

• host, siteUrl - see installation for details.
• forcePrerender - removed (no longer needed)
• satoriProvider - removed (use runtimeSatori instead)
• browserProvider - removed (use runtimeBrowser instead)
• experimentalInlineWasm - we removed this; it's now automatic based on environment
• experimentalRuntimeBrowser - we removed this; it's now automatic based on environment

The following options have been deprecated from the defineOgImage options:

• static - use cache instead

If you were referencing the old default template, you will need to update it.

• OgImageBasic - remove the property and let the system select the fallback automatically

Composables & Components:

• defineOgImageStatic() is deprecated, use defineOgImage() (default behavior is to cache), if you want to be verbose you can use defineOgImageCached() or <OgImageCached />
• <OgImageStatic /> is deprecated, use <OgImage />
• defineOgImageDynamic() is deprecated, use defineOgImageWithoutCache()
• <OgImageDynamic /> is deprecated, use <OgImageWithoutCache />

If you were using the runtime browser previously, you will need to manually opt-in for it to work in production.

export default defineNuxtConfig({
  ogImage: {
    runtimeBrowser: true
  }
})

<script setup lang="ts">
defineOgImageStatic(
  { /* */ }
)
</script>

<script setup lang="ts">
defineOgImage(
  { /* */ }
)
</script>

Nuxt Link Checker

Upgraded from v1 to v2:

• v2 release notes

Changes to nuxt.config linkChecker:

• exclude renamed to excludeLinks
• failOn404 renamed to failOnError

Nuxt SEO Utils

The nuxt-unhead module has been renamed to nuxt-seo-utils. This is to better reflect the scope of the module.

Upgraded from v1 to v3:

• v2 release notes
• v3 release notes

If you were using the unhead key to configure the module, you will need to change it to seo.

export default defineNuxtConfig({
-  unhead: {
+  seo: {
  }
})