Nuxt SEO Utils

nuxt-seo-utils

Requires Nuxt ^4.6.0 || ^5.0.0 and Unhead 3.4.2 or newer. The module adds default head tags from site config, reads icon and social image files, and ships breadcrumb and share link composables. Docs: https://nuxtseo.com/docs/seo-utils

Setup

The config key is seo. seoUtils does nothing. Set site.url and site.name. The canonical URL, og:url, the title template, and absolute image URLs read them.

export default defineNuxtConfig({
  modules: ['nuxt-seo-utils'],
  site: { url: 'https://example.com', name: 'Acme', description: 'Default description', twitter: 'acme', defaultLocale: 'en-US' },
})

Crawlers read only the SSR response. The defaults render on the server.

Automatic behaviour

With the defaults, every page gets:

• <title> from the template %s %separator %siteName. The separator is |. Change it with site.separator.
• A fallback title from the last path segment, title cased: /blog/my-post becomes My Post. definePageMeta({ title }) sets it with a static string.
• <link rel="canonical"> from site.url and the route path, lowercased, with only these query keys kept: page, sort, filter, search, q, category, tag.
• og:url (the resolved canonical, including one a page sets), og:type (website), og:site_name (site.name), and description from site.description.
• og:title, og:description, and twitter:card (summary_large_image), inferred from the title and description.
• twitter:site and twitter:creator from site.twitter. The @ is added.
• <html lang> from site.currentLocale or site.defaultLocale, else en.
• og:locale only when the locale has a region. en-US renders en_US. en renders no tag.
• Relative og:image and twitter:image values become absolute against site.url.

Module tags use tagPriority: 'low', so a page useSeoMeta() or useHead() call replaces them. A page ogImage also drops the default image's width, height, type, and copied twitter:image. A page ogImageAlt alone keeps the default image. A page canonical needs no extra priority:

useHead({ link: [{ rel: 'canonical', href: 'https://example.com/preferred' }] })

Set seo: { automaticDefaults: false } to drop the canonical, title template, lang, and Open Graph defaults together. No option drops only one of them.

Metadata files

Files in public/ become site-wide head tags at build time:

• favicon.{ico,png,svg}, icon*.{ico,png,jpg,svg}, apple-icon*.png, apple-touch-icon*.png: <link rel="icon"> or apple-touch-icon, with type and sizes read from the file.
• og-image.{png,jpg,jpeg,gif} or opengraph-image.*: og:image with width, height, and type. It also fills twitter:image when no twitter-image.* file exists. The name must match exactly; blog-og-image.png is ignored.
• <name>.alt.txt next to an image sets og:image:alt.
• -dark or -light in an icon name adds a prefers-color-scheme media query.

The same file names inside pages/<route>/ or pages/<route>/_dir/ apply to that route and its children. They replace a public/ image there. An icon link in app.head.link with the same rel wins over the files. Set seo: { metaDataFiles: false } to turn this off.

Generate icon files from one source image in public/:

pnpm exec nuxt-seo-utils icons --source logo.svg

It writes favicon.ico, apple-touch-icon.png, and icon-{16,32,192,512} PNGs to public/. Install the optional peer with pnpm add -D sharp before generating icons.

Site-wide and per-route meta

seo.meta takes useSeoMeta() input and renders on every page:

export default defineNuxtConfig({
  seo: { meta: { author: 'Acme Team', themeColor: '#18181b' } },
})

routeRules accept seoMeta and head:

export default defineNuxtConfig({
  routeRules: {
    '/blog/**': { seoMeta: { author: 'Blog Team' }, head: { meta: [{ name: 'x-section', content: 'blog' }] } },
  },
})

Route rule tags override seo.meta and app.head. A page useSeoMeta() or useHead() call overrides them. The tagPriority option does not change this. Route rule tags render on the server only. They do not update on client navigation.

Breadcrumbs

useBreadcrumbItems() is auto-imported. It returns a ref of items from the route path, ready for Nuxt UI <UBreadcrumb :items>.

const items = useBreadcrumbItems({
  overrides: [undefined, undefined, { label: post.value.title }], // index matches the path segment; false removes it
})

• With nuxt-schema-org installed, it also adds a BreadcrumbList node. Without it, no JSON-LD renders and there is no warning.
• Labels come from definePageMeta({ breadcrumb: { label } }), then title in page meta, then the title-cased segment. The index route is Home.
• Call it in the page component, not the layout. The page has the data for the last items. Calls in parent components with the same id merge their options.