Upgrade Guide

Migrate to v3 (from v2)

Unhead v3 removes all deprecated APIs and focuses on performance improvements.

Legacy Property Names

🚦 Impact Level: High

The DeprecationsPlugin that automatically converted legacy property names has been removed. You must update your head entries to use the current property names.

children → innerHTML

useHead({
  script: [{
-   children: 'console.log("hello")',
+   innerHTML: 'console.log("hello")',
  }]
})

hid / vmid → key

useHead({
  meta: [{
-   hid: 'description',
+   key: 'description',
    name: 'description',
    content: 'My description'
  }]
})

body: true → tagPosition: 'bodyClose'

useHead({
  script: [{
    src: '/script.js',
-   body: true,
+   tagPosition: 'bodyClose',
  }]
})

Schema.org Plugin

🚦 Impact Level: High

If you're using @unhead/schema-org, the plugin exports have changed:

- import { SchemaOrgUnheadPlugin } from '@unhead/schema-org'
+ import { UnheadSchemaOrg } from '@unhead/schema-org'

const head = createHead({
  plugins: [
-   SchemaOrgUnheadPlugin()
+   UnheadSchemaOrg()
  ]
})

Core API Changes

🚦 Impact Level: Medium

headEntries() → entries Map

- const entries = head.headEntries()
+ const entries = [...head.entries.values()]

mode Option Removed

The mode option on head entries has been removed. Use conditional logic instead:

if (typeof window !== 'undefined') {
  useHead({ title: 'Client Only' })
}

Hooks

🚦 Impact Level: Low

The following hooks have been removed:

• init - No longer needed
• dom:renderTag - DOM rendering is now synchronous
• dom:rendered - Use code after renderDOMHead() instead

The dom:beforeRender hook is now synchronous and renderDOMHead no longer returns a Promise:

- await renderDOMHead(head, { document })
+ renderDOMHead(head, { document })

The SSR hooks (ssr:beforeRender, ssr:render, ssr:rendered) are now synchronous and renderSSRHead no longer returns a Promise:

- const head = await renderSSRHead(head)
+ const head = renderSSRHead(head)