useSeoMeta Transform

The useSeoMeta transform rewrites statically analyzable useSeoMeta() calls into equivalent useHead() calls at build time. This can remove runtime meta-key resolution code from the bundle. The transform is enabled by default and also handles the deprecated useServerSeoMeta().

Transformation

At build time, useSeoMeta() calls with static or semi-static arguments are converted to useHead() with pre-resolved meta arrays:

useSeoMeta(unheadInstance, {
  title: 'My Title',
  description: 'My Description',
  ogImage: 'https://example.com/image.png',
})

useHead(unheadInstance, {
  title: 'My Title',
  meta: [
    { name: 'description', content: 'My Description' },
    { property: 'og:image', content: 'https://example.com/image.png' },
  ],
})

When a call is transformed, its import specifier is also rewritten: import { useSeoMeta } from 'unhead' becomes import { useHead } from 'unhead'.

Setup

The transform is enabled by default when using the unified Vite plugin:

import { Unhead } from '@unhead/vue/vite'

export default defineConfig({
  plugins: [Unhead()],
})

Disable

Unhead({
  transformSeoMeta: false,
})

Options

Unhead({
  transformSeoMeta: {
    // Disable import specifier rewriting
    imports: false,
    // Extra import paths to recognize as useSeoMeta sources
    importPaths: ['my-custom-package'],
    // Override the shared file filter
    filter: {
      include: [/my-special-file/],
      exclude: [/some-file/],
    },
  },
})

Limitations

The transform skips calls it cannot statically analyze:

• A non-object or dynamic first argument
• Spread elements in the options object (useSeoMeta({ ...dynamicMeta }))
• Non-identifier keys
• Properties with missing values
• Packed object fields such as robots whose keys or values are not static strings
• Structured media objects whose shape uses spreads, computed keys, getters, setters, or methods. Their leaf values may be dynamic when the object shape itself is static

In these cases, the original useSeoMeta() call is preserved and resolved at runtime.

Deprecated useServerSeoMeta

The transform also handles the deprecated useServerSeoMeta(). When it includes title or titleTemplate, the transform splits the call into two: a useHead() call for the title fields and a useServerHead() call for the meta tags.

// Input (deprecated)
useServerSeoMeta({ title: 'My Title', description: 'My Desc' })

// Output
useHead(unheadInstance, { title: 'My Title' })
useServerHead(unheadInstance, { meta: [{ name: 'description', content: 'My Desc' }] })

New code should use useSeoMeta() instead.