Star
1.1K

Support

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

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 at its core 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
nuxt.config.ts
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 flexible 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'
    }
  }
})

When updating your config:

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

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

Prerendering Changes

In v1, it was required to prerender all pages, to ensure this happened your nuxt.config was modified.

In v2, everything can be generated at runtime and the prerendering changes are no longer provided.

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:

No breaking changes.

Nuxt Sitemap

Upgraded from v1 to v3:

No breaking changes.

Nuxt Schema.org

Upgraded from v2 to v3:

No breaking changes.

Nuxt OG Image

Upgraded from v1 to v2:

The following options have been removed from nuxt.config ogImage:

  • host, siteUrl - see installation for details.
  • forcePrerender - removed, not needed
  • satoriProvider - removed use runtimeSatori
  • browserProvider - removed use runtimeBrowser
  • experimentalInlineWasm - removed, this is now automatic based on environment
  • experimentalRuntimeBrowser - removed, this is 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, allow the fallback to be selected automatically

Composables & Components:

  • defineOgImageStatic() is deprecated, use defineOgImage() (default behaviour 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>
defineOgImageStatic({ /* */ })
</script>

Nuxt Link Checker

Upgraded from v1 to v2:

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:

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

export default defineNuxtConfig({
-  unhead: {
+  seo: {
  }
})
Edit this page
Did this page help you?