---
title: "Migrate to v2"
description: "Migrate from Unhead v1 to v2, including subpath exports, explicit context, and opt-in plugins."
canonical_url: "https://unhead.unjs.io/docs/migration-guide/v2"
last_updated: "2026-07-21T05:13:04.774Z"
---
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:**
```diff
-import { createServerHead } from 'unhead'
+import { createHead } from 'unhead/client'
// avoids bundling server plugins
createHead()
```
**Server bundle:**
```diff
-import { createServerHead } from 'unhead'
+import { createHead } from 'unhead/server'
// avoids bundling server plugins
-createServerHead()
+createHead()
```
---
## 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 required when importing composables from `unhead`. Framework adapters retrieve it from their own context.
```ts [TypeScript v2]
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](/docs/migration-guide/v3#legacy-property-names) for the replacements.
---
## Opt-in Template Params & Tag Alias Sorting
🚦 Impact Level: **High**
Template parameters and tag alias sorting now require optional plugins:
```ts
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:
```ts
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
```diff
const script = useScript()
-script.then(() => console.log('loaded')
+script.onLoaded(() => console.log('loaded'))
```
### Replacing Proxy Usage
```diff
const script = useScript('..', {
use() { return { foo: [] } }
})
-script.foo.push('bar')
+script.proxy.foo.push('bar')
```
---
## Tag Sorting Updated
🚦 Impact Level: **Low**
[Capo.js](https://rviscomi.github.io/capo.js/) sorting is now the default. You can opt-out:
```ts
createHead({
disableCapoSorting: true,
})
```
---
## Default SSR Tags
🚦 Impact Level: **Low**
During SSR, Unhead now inserts these default tags:
- ``
- ``
- ``
```ts
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.
```diff
-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.
```diff
-import type { HeadTag } from '@unhead/schema'
+import type { HeadTag } from 'unhead/types'
```