Migrate to v2 · Unhead [Unhead Home](https://unhead.unjs.io/ "Home") - [Docs](https://unhead.unjs.io/docs/typescript/head/guides/get-started/overview) - [Tools](https://unhead.unjs.io/tools) - [Learn](https://unhead.unjs.io/learn/guides/what-is-capo) [Releases](https://unhead.unjs.io/releases) Search…```k`` /` [Unhead on GitHub](https://github.com/unjs/unhead) [User Guides](https://unhead.unjs.io/docs/typescript/head/guides/get-started/overview) [API](https://unhead.unjs.io/docs/typescript/head/api/get-started/overview) [Releases](https://unhead.unjs.io/docs/typescript/releases/v3) TypeScript - [Switch to TypeScript](https://unhead.unjs.io/docs/typescript/migration-guide/v2) - [Switch to Vue](https://unhead.unjs.io/docs/vue/migration-guide/v2) - [Switch to React](https://unhead.unjs.io/docs/react/migration-guide/v2) - [Switch to Svelte](https://unhead.unjs.io/docs/svelte/migration-guide/v2) - [Switch to Solid.js](https://unhead.unjs.io/docs/solid-js/migration-guide/v2) - [Switch to Angular](https://unhead.unjs.io/docs/angular/migration-guide/v2) - [Switch to Nuxt](https://unhead.unjs.io/docs/nuxt/migration-guide/v2) v3 (stable) Head - [Discord Support](https://discord.com/invite/275MBUBvgP) - [TypeScript Playground](https://stackblitz.com/edit/github-hhxywsb5) - Releases - [v3](https://unhead.unjs.io/docs/typescript/releases/v3) - [v2](https://unhead.unjs.io/docs/typescript/releases/v2) - Migration Guide - [v3](https://unhead.unjs.io/docs/typescript/migration-guide/v3) - [v2](https://unhead.unjs.io/docs/typescript/migration-guide/v2) Migration Guide # Migrate to v2 [Copy for LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/6.migration-guide/2.v2.md) Last updated Apr 9, 2026 by [Harlan Wilton](https://github.com/harlan-zw) in [refactor(bundler)!: named Unhead export, ctx-based transforms, dev-mode validate (#733)](https://github.com/unjs/unhead/pull/733). On this page - [Client / Server Subpath Exports](#client-server-subpath-exports) - [Removed Implicit Context](#removed-implicit-context) - [Removed vmid, hid, children, body](#removed-vmid-hid-children-body) - [Opt-in Template Params & Tag Alias Sorting](#opt-in-template-params-tag-alias-sorting) - [Promise Input Support](#promise-input-support) - [Updated useScript()](#updated-usescript) - [Tag Sorting Updated](#tag-sorting-updated) - [Default SSR Tags](#default-ssr-tags) - [CJS Exports Removed](#cjs-exports-removed) - [Deprecated @unhead/schema](#deprecated-unheadschema) With the release of Unhead v2, we now have first-class support for other frameworks. This guide covers the v1 to v2 migration. ## [Client / Server Subpath Exports](#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() ``` --- ## [Removed Implicit Context](#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. Passing the instance is only relevant if you're importing from `unhead`. In JavaScript frameworks we tie the context to the framework itself so you don't need to worry about this. TypeScript v2 ``` import { useHead } from 'unhead' // example of getting the instance const unheadInstance = useMyApp().unhead useHead(unheadInstanceunheadInstance, , { title: 'Looks good' }) ``` --- ## [Removed `vmid`, `hid`, `children`, `body`](#removed-vmid-hid-children-body) 🚦 Impact Level: **High** For legacy support with Vue Meta we allowed end users to provide deprecated properties: `vmid`, `hid`, `children` and `body`. You must update these properties to the appropriate replacement or remove them. See the [v3 migration guide](https://unhead.unjs.io/docs/typescript/migration-guide/v3#legacy-property-names) for the replacements. --- ## [Opt-in Template Params & Tag Alias Sorting](#opt-in-template-params-tag-alias-sorting) 🚦 Impact Level: **High** To reduce the bundle size and improve performance, we've moved the template params and tag alias sorting to optional plugins. ``` import { AliasSortingPlugin, TemplateParamsPlugin } from 'unhead/plugins' createHead({ plugins: [TemplateParamsPlugin, AliasSortingPlugin] }) ``` --- ## [Promise Input Support](#promise-input-support) 🚦 Impact Level: **Medium** If you have promises as input they will no longer be resolved, either await the promise before passing it along or register the optional promises plugin. ``` import { PromisePlugin } from 'unhead/plugins' const unhead = createHead({ plugins: [PromisePlugin] }) ``` --- ## [Updated `useScript()`](#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('..', { use() { return { foo: [] } } }) -script.foo.push('bar') +script.proxy.foo.push('bar') ``` --- ## [Tag Sorting Updated](#tag-sorting-updated) 🚦 Impact Level: **Low** [Capo.js](https://rviscomi.github.io/capo.js/) sorting is now the default. You can opt-out: ``` createHead({ disableCapoSorting: true, }) ``` --- ## [Default SSR Tags](#default-ssr-tags) 🚦 Impact Level: **Low** When SSR Unhead will now insert important default tags for you: - `` - `` - `` ``` import { createHead } from 'unhead/server' // disable when creating the head instance const head = createHead({ disableDefaults: true, }) ``` --- ## [CJS Exports Removed](#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`](#deprecated-unheadschema) 🚦 Impact Level: **Low** The `@unhead/schema` package is deprecated. Import from `unhead/types` or `unhead` instead. ``` -import { HeadTag } from '@unhead/schema' +import { HeadTag } from 'unhead/types' ``` [Edit this page](https://github.com/unjs/unhead/edit/main/docs/6.migration-guide/2.v2.md) [Markdown For LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/6.migration-guide/2.v2.md) Did this page help you? [v3 Migrate from Unhead v2 to v3. Covers all breaking changes, removed APIs, and their replacements.](https://unhead.unjs.io/docs/migration-guide/v3) [v3 Unhead v3 release notes: streaming SSR, unified Vite plugin with devtools, and significant performance improvements.](https://unhead.unjs.io/docs/releases/v3) On this page - [Client / Server Subpath Exports](#client-server-subpath-exports) - [Removed Implicit Context](#removed-implicit-context) - [Removed vmid, hid, children, body](#removed-vmid-hid-children-body) - [Opt-in Template Params & Tag Alias Sorting](#opt-in-template-params-tag-alias-sorting) - [Promise Input Support](#promise-input-support) - [Updated useScript()](#updated-usescript) - [Tag Sorting Updated](#tag-sorting-updated) - [Default SSR Tags](#default-ssr-tags) - [CJS Exports Removed](#cjs-exports-removed) - [Deprecated @unhead/schema](#deprecated-unheadschema) [GitHub](https://github.com/unjs/unhead) [ Discord](https://discord.com/invite/275MBUBvgP) [ /llms.txt](https://unhead.unjs.io/llms.txt) [Part of the UnJS ecosystem](https://unjs.io/) ### Head Management - [Getting Started](https://unhead.unjs.io/docs/typescript/head/guides/get-started/overview) - [useHead](https://unhead.unjs.io/docs/typescript/head/api/composables/use-head) - [useSeoMeta](https://unhead.unjs.io/docs/typescript/head/api/composables/use-seo-meta) - [useHeadSafe](https://unhead.unjs.io/docs/typescript/head/api/composables/use-head-safe) - [useScript](https://unhead.unjs.io/docs/typescript/head/api/composables/use-script) ### Schema.org - [Getting Started](https://unhead.unjs.io/docs/typescript/schema-org/guides/get-started/overview) - [useSchemaOrg](https://unhead.unjs.io/docs/typescript/schema-org/api/composables/use-schema-org) - [Nodes](https://unhead.unjs.io/docs/typescript/schema-org/guides/core-concepts/nodes) - [Recipes](https://unhead.unjs.io/docs/typescript/schema-org/guides/recipes/identity) ### Guides - [Titles](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/titles) - [Streaming SSR](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/streaming) - [DOM Events](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/dom-event-handling) - [Plugins](https://unhead.unjs.io/docs/typescript/head/guides/plugins/template-params) ### Tools - [Meta Tag Generator](https://unhead.unjs.io/tools/meta-tag-generator) - [OG Image Generator](https://unhead.unjs.io/tools/og-image-generator) - [Schema.org Generator](https://unhead.unjs.io/tools/schema-generator) - [Capo.js Analyzer](https://unhead.unjs.io/tools/capo-analyzer) ### Articles - [What is Capo.js?](https://unhead.unjs.io/learn/guides/what-is-capo) ### Research - [State of in 2026](https://unhead.unjs.io/learn/research/state-of-head-2026) - [Streaming Head Performance](https://unhead.unjs.io/learn/research/streaming-head-performance) - [Capo.js Performance Research](https://unhead.unjs.io/learn/research/capo-performance-research) Copyright © 2025-2026 Harlan Wilton - [MIT License](https://github.com/unjs/unhead/blob/main/license)