Migrate to v2

Unhead v2 adds framework adapters and changes several core entry points. This guide covers the required updates from v1.

Client / Server Subpath Exports

🚦 Impact Level: Critical

⚠️ Breaking Changes:

• createServerHead() and createHead() exports from unhead are removed

The path where you import createHead from has been updated to be a subpath export.

Client bundle:

-import { createServerHead } from 'unhead'
+import { createHead } from 'unhead/client'

// avoids bundling server plugins
createHead()

Server bundle:

-import { createServerHead } from 'unhead'
+import { createHead } from 'unhead/server'

// avoids bundling server plugins
-createServerHead()
+createHead()

Create the browser head once. For SSR, create a fresh server head for each request rather than reusing the browser instance.

Replace Legacy Alias Packages

Move direct imports from the compatibility packages to their v2 entry points:

Removed Implicit Context

🚦 Impact Level: Critical

⚠️ Breaking Changes:

• getActiveHead(), activeHead exports are removed

The implicit context implementation kept a global instance of Unhead available so that you could use the useHead() composables anywhere in your application.

In v2, the core composables no longer have access to the Unhead instance. Instead, you must pass the Unhead instance to the composables.

import { useHead } from 'unhead'

// example of getting the instance
const unheadInstance = useMyApp().unhead
useHead(unheadInstance, {
  title: 'Looks good'
})

Removed vmid, hid, children, body

🚦 Impact Level: High

Unhead v1 accepted the Vue Meta properties vmid, hid, children, and body.

You must update these properties to the appropriate replacement or remove them. See the v3 migration guide for the replacements.

Opt-in Template Params & Tag Alias Sorting

🚦 Impact Level: High

Template parameters and tag alias sorting now require optional plugins:

import { AliasSortingPlugin, TemplateParamsPlugin } from 'unhead/plugins'

createHead({
  plugins: [TemplateParamsPlugin, AliasSortingPlugin]
})

Promise Input Support

🚦 Impact Level: Medium

Promise inputs are no longer resolved by core. Prefer awaiting them before passing the result to Unhead, or register the optional plugin when that is not possible:

import { PromisesPlugin } from 'unhead/plugins'

const unhead = createHead({
  plugins: [PromisesPlugin]
})

The plugin resolves values outside the synchronous tag pipeline. Pending entries are omitted from the current render, then rendered automatically on the client after resolving. Resolve inputs before SSR when they must appear in its first render.

Updated useScript()

🚦 Impact Level: High

⚠️ Breaking Changes:

• Script instance is no longer augmented as a proxy and promise
• script.proxy is rewritten for simpler, more stable behavior
• stub() and runtime hook script:instance-fn are removed

Replacing Promise Usage

const script = useScript()

-script.then(() => console.log('loaded')
+script.onLoaded(() => console.log('loaded'))

Replacing Proxy Usage

const script = useScript(unheadInstance, '..', {
  use() { return { foo: [] } }
})

-script.foo.push('bar')
+script.proxy.foo.push('bar')

Tag Sorting Updated

🚦 Impact Level: Low

Capo.js sorting is now the default. You can opt-out:

createHead({
  disableCapoSorting: true,
})

Default SSR Tags

🚦 Impact Level: Low

During SSR, Unhead now inserts these default tags:

• <meta charset="utf-8">
• <meta name="viewport" content="width=device-width, initial-scale=1">
• <html lang="en">

import { createHead } from 'unhead/server'

// disable when creating the head instance
const head = createHead({
  disableDefaults: true,
})

CJS Exports Removed

🚦 Impact Level: Low

CommonJS exports have been removed in favor of ESM only.

-const { createHead } = require('unhead/client')
+import { createHead } from 'unhead/client'

Deprecated @unhead/schema

🚦 Impact Level: Low

The @unhead/schema package is deprecated. Import from unhead/types or unhead instead.

-import type { HeadTag } from '@unhead/schema'
+import type { HeadTag } from 'unhead/types'