Skip to main content
skill CX Codex

unhead-vue-skilld — Claude Code skill: what it does, how to install

unhead-vue-skilld guides AI coding agents through document head management, SEO metadata, and script loading in Vue 3 applications via @unhead/vue.

MIT 105 installs ★ 186 updated 2026-10-10

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add skilld-dev/vue-ecosystem-skills --skill unhead-vue-skilld -a claude-code
Open on GitHub

What unhead-vue-skilld does

The skill provides patterns and edge-case rules for @unhead/vue 3.4.1. It covers client hydration, full SSR template integration, streaming SSR, and bundler plugins for Vite or Webpack. Core composables covered include useHead, useSeoMeta, useHeadSafe, and useScript.

It flags breaking changes from earlier releases. For instance, createHead must be imported from subpaths like @unhead/vue/client or @unhead/vue/server rather than the package root. It also prevents duplicate tags by enforcing the key attribute instead of outdated hid identifiers, and warns against calling useHead inside watcher callbacks.

The target project requires vue >= 3.5.18 and standard ESM, as Vue 2 and CommonJS are unsupported. Nuxt projects already bundle Unhead, so installing manual setup code there will conflict.

What it helps with

  • wire client and server createHead instances in custom Vue 3 SSR pipelines
  • generate type-safe Open Graph and Twitter tags with useSeoMeta
  • resolve provide context missing errors caused by async useHead calls
  • load third-party tracking scripts lazily with useScript proxies
  • sanitize dynamic user metadata using useHeadSafe

Example prompts for the agent

  • Set up Unhead SSR in entry-server.ts using createHead from @unhead/vue/server
  • Generate dynamic Open Graph metadata for the product view with useSeoMeta
  • Fix the provide context error on this async useHead call

How to install unhead-vue-skilld

1Skills CLI (Vercel)

npx skills add skilld-dev/vue-ecosystem-skills --skill unhead-vue-skilld -a claude-code

2Manually: put the files in place

~/.claude/skills/unhead-vue-skilld/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/unhead-vue-skilld/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about unhead-vue-skilld

How to install unhead-vue-skilld in Claude Code?

Run npx skills add skilld-dev/vue-ecosystem-skills --skill unhead-vue-skilld -a claude-code in your terminal.

What does unhead-vue-skilld do?

It feeds the agent correct API signatures, subpath imports, and reactivity rules for @unhead/vue 3.x.

Is this skill needed for Nuxt projects?

No. Nuxt already includes built-in Unhead integration, so manual initialization is unnecessary.

Source text

SKILL.md · MIT
---
name: unhead-vue-skilld
description: Full-stack <head> manager for Vue (@unhead/vue 3.x). Use when writing, reviewing, or debugging code that imports @unhead/vue, calls useHead, useSeoMeta, useHeadSafe, useScript, injectHead, createHead, or sets up Unhead SSR / streaming SSR / build plugins in a Vue app.
license: MIT
---

# @unhead/vue 3.4.1

Full-stack `<head>` management for Vue 3. ESM only (`"type": "module"`), no CJS.
Peer deps: `vue >= 3.5.18`; optional `vite >= 6.4.2`, `webpack >= 5.0.0` (source: `package.json:138-150`).
Vue 2: not supported; use `@unhead/vue@^1`.
Nuxt: Unhead is integrated already; do not install or set it up manually.

## Setup (mandatory)

Install `@unhead/vue`, create the head instance, and register it as a Vue plugin. `createHead` comes from a subpath export, not the package root.

```ts
// entry-client.ts (SPA or hydration)
import { createHead } from '@unhead/vue/client'
import { createApp } from './main'

const { app } = createApp()
const head = createHead()
app.use(head)
app.mount('#app')
```

```ts
// entry-server.ts (SSR)
import { createHead } from '@unhead/vue/server'
import { renderToString } from 'vue/server-renderer'
import { createApp } from './main'

export async function render(url: string) {
  const { app } = createApp()
  const head = createHead()
  app.use(head)
  const html = await renderToString(app)
  return { html, head } // render tags later with transformHtmlTemplate(head, template)
}
```

Full SSR template wiring, streaming SSR, Options API, and auto-imports: [references/setup.md](references/setup.md).

## Composables

All imported from `@unhead/vue` root and used inside `setup()`:

```vue
<script setup lang="ts">
import { useHead, useSeoMeta } from '@unhead/vue'

useHead({
  title: () => `${user.value.name} - Profile`, // getters, refs, computed all reactive
  titleTemplate: '%s | My Site',
  meta: [{ name: 'description', content: () => description.value }],
})

useSeoMeta({ // flat, type-safe keys; og/twitter handled automatically
  ogTitle: 'My Page',
  ogImage: 'https://example.com/image.jpg',
})
</script>
```

```ts
// Third-party scripts
import { useScript } from '@unhead/vue'

const { proxy, onLoaded, status } = useScript(
  { src: 'https://example.com/analytics.js' },
  { use: () => window.analytics, trigger: 'client' },
)
proxy.track('pageview') // queued until the script loads
```

Details, options tables, and recipes: [references/composables.md](references/composables.md).

## Critical rules

1. **Async context**: calling `useHead()` after an `await` inside `onMounted()`/watchers throws `useHead() was called without provide context`. Fix, in order of preference: top-level `await` in `<script setup>`; declare `useHead()` once with refs/computed and update the ref later; capture `const head = injectHead()` at setup time and pass `useHead(input, { head })`. Source: https://unhead.unjs.io/docs/vue/head/guides/core-concepts/reactivity-and-context
2. **Never call `useHead()` inside a watcher callback**: each call pushes a new entry and duplicates tags. Pass the reactive value into one `useHead()` call instead.
3. **Deduplication key is `key`**, not `hid`/`vmid`: `meta: [{ key: 'description', name: 'description', content: '...' }]`.
4. **Inline content**: `innerHTML` (was `children` in v1); body scripts use `tagPosition: 'bodyClose'` (was `body: true`).
5. **Untrusted input**: use `useHeadSafe()`; it whitelists attributes and strips scripts/handlers.
6. **Head instance access in Vue**: use `injectHead()` from `@unhead/vue`, not `getActiveHead()` from `unhead`; only the former binds to component context (e.g. `onServerPrefetch`).

## Deprecated in 3.4.1 (present but slated for removal)

| Export | Status | Replacement |
|---|---|---|
| `useServerHead`, `useServerHeadSafe`, `useServerSeoMeta` | deprecated (`dist/index.d.ts:26-30`) | `useHead` / `useHeadSafe` / `useSeoMeta` |
| `@unhead/vue/legacy` (`createHead`, `createServerHead`, `legacyPlugins`) | deprecated, removed in v4 (`dist/legacy.d.ts:14-30`) | `@unhead/vue/client` / `@unhead/vue/server` |
| `resolveUnrefHeadInput` | deprecated (`dist/utils.d.ts:9`) | `resolveTags(head)` from `unhead/utils` |
| `unheadVuePlugin` from `@unhead/vue/stream/vite` | deprecated (`dist/stream/vite.d.ts:8`) | `Unhead({ streaming: true }).vite()` from `@unhead/vue/bundler` |
| `MergeHead` type | deprecated (`dist/types.d.ts:66`) | generics on `VueHeadClient` |

Removed in v3 (will not compile): `DeprecationsPlugin`, `setHeadInjectionHandler`, `createHeadCore`, `{ mode: 'server' | 'client' }` entry option, `init`/`dom:renderTag`/`dom:rendered` hooks, `headEntries()` (use `[...head.entries.values()]`).
Migration details: [references/migration.md](references/migration.md).

## Export map

| Subpath | Purpose |
|---|---|
| `@unhead/vue` | composables: `useHead`, `useSeoMeta`, `useHeadSafe`, `useScript`, `injectHead`, `VueHeadMixin`, `unheadVueComposablesImports`, `createUnhead`, `defineLink`, `defineScript` |
| `@unhead/vue/client` | `createHead()` (SPA/hydration), `renderDOMHead`, `VueHeadMixin` |
| `@unhead/vue/server` | `createHead()` (SSR), `renderSSRHead`, `transformHtmlTemplate`, `propsToString` |
| `@unhead/vue/components` | `<Head>` component |
| `@unhead/vue/plugins` | re-exports `unhead/plugins` (`TemplateParamsPlugin`, `AliasSortingPlugin`, `PromisePlugin`, `InferSeoMetaPlugin`, `ValidatePlugin`, ...) |
| `@unhead/vue/bundler` | unified build plugin `Unhead()` for vite/webpack/rspack/rollup |
| `@unhead/vue/vite` | Vite-only `Unhead()`; prefer `/bundler` |
| `@unhead/vue/stream/server`, `/stream/client` | `createStreamableHead()` for streaming SSR |
| `@unhead/vue/types`, `/utils`, `/scripts`, `/legacy` | types, utilities, script types, legacy shims |

Signatures and full type surface: [references/api-surface.md](references/api-surface.md).

## Optional plugins at creation

Template params (`%s`, `%separator`), alias sorting (`before:`/`after:`), and Promise inputs are opt-in since v2:

```ts
import { createHead } from '@unhead/vue/client'
import { AliasSortingPlugin, TemplateParamsPlugin } from '@unhead/vue/plugins'

const head = createHead({ plugins: [TemplateParamsPlugin, AliasSortingPlugin] })
```

Without `TemplateParamsPlugin`, `%siteName` placeholders render literally.

## Build plugin (recommended for standalone Vue apps)

```ts
// vite.config.ts
import { Unhead } from '@unhead/vue/bundler'

export default defineConfig({
  plugins: [vue(), Unhead()], // add { streaming: true } for streaming SSR
})
```

Tree-shakes server-only composables from the client bundle, converts `useSeoMeta()` to `useHead()` (~3kb), injects `ValidatePlugin` in dev. Options table and webpack notes: [references/build-plugins.md](references/build-plugins.md).

## Common mistakes

- Importing `createHead` from `@unhead/vue` root (removed in v2): use `/client` or `/server`.
- Awaiting `renderSSRHead` / `renderDOMHead`: both are synchronous in v3.
- `useScript()` return is not a Promise: use `onLoaded(() => ...)`; call APIs through `.proxy`.
- Meta tags require `content`: `{ name: 'description', content: null }` removes the tag.
- Font preloads require `crossorigin`: `{ rel: 'preload', as: 'font', href: '/f.woff2', crossorigin: 'anonymous' }`.

## References

- [references/setup.md](references/setup.md) — SPA, SSR, streaming SSR, Options API, `<Head>` component, auto-imports, defaults
- [references/composables.md](references/composables.md) — `useHead`, `useSeoMeta`, `useHeadSafe`, `useScript` usage and options
- [references/api-surface.md](references/api-surface.md) — export map, types, instance API
- [references/build-plugins.md](references/build-plugins.md) — `Unhead()` bundler plugin and streaming
- [references/migration.md](references/migration.md) — v2 and v3 breaking changes

© skilld-dev · MIT · skilld-dev/vue-ecosystem-skills

Similar skills

All skills for Frontend and UI →

From the same set32

The whole set →
floating-ui-vue-skilld floating-ui-vue-skilld guides AI coding agents on anchoring tooltips, popovers, and menus using @floating-ui/vue 2.0.1 in Vue 3.3+. CX Codex +1 119installs vue-data-ui-skilld The vue-data-ui-skilld skill guides agents working with the vue-data-ui Vue 3 chart library, from component selection and theming to SSR and debugging. CX Codex +1 118installs unovis-vue-skilld unovis-vue-skilld is a Claude Code skill for building and debugging Vue 3 code with @unovis/vue, including chart work and migration to API 1.7.0. CX Codex +1 112installs vitepress-skilld vitepress-skilld supplies API specs, config references, and CLI instructions for VitePress 1.6.4. CX Codex +1 110installs tanstack-ai-vue-skilld The tanstack-ai-vue-skilld skill guides Vue 3 work with @tanstack/ai-vue, covering streaming chat, media generation, reactive state, and typed client tools. CX Codex +1 110installs formkit-core-skilld formkit-core-skilld is a Claude Code skill for writing, debugging, and checking code that uses FormKit core nodes, values, events, and hooks. CX Codex +1 105installs tanstack-vue-router-skilld tanstack-vue-router-skilld — a skill for working with @tanstack/vue-router, the type-safe Vue router. Teaches the agent setup rules, file-based routes, composables returning Ref, links and loaders. CX Codex +1 101installs tanstack-vue-store-skilld tanstack-vue-store-skilld — a skill for Claude Code that guides state management implementations using @tanstack/vue-store. Triggers whenever components import code from the library in a Vue application. CX Codex +1 100installs

Project sponsors

Companies that keep this analytics open