unhead-vue-skilld

Full-stack head manager built for Vue. ALWAYS use when writing code importing "@unhead/vue". Consult for debugging, best practices, or modifying @unhead/vue, unhead/vue, unhead vue, unhead.

Safety Notice

This listing is imported from skills.sh public index metadata. Review upstream SKILL.md and repository scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "unhead-vue-skilld" with this command: npx skills add harlan-zw/vue-ecosystem-skills/harlan-zw-vue-ecosystem-skills-unhead-vue-skilld

unjs/unhead @unhead/vue

Full-stack <head> manager built for Vue.

Version: 2.1.12 (Mar 2026) Deps: hookable@^6.0.1, unhead@2.1.12 Tags: next: 3.0.0-beta.9 (Feb 2026), beta: 3.0.0-beta.12 (Mar 2026), latest: 2.1.12 (Mar 2026)

References: Docs — API reference, guides

API Changes

This section documents version-specific API changes — prioritize recent major/minor releases.

  • BREAKING: createHead() and createServerHead() removed from @unhead/vue root in v2 — use subpath imports: createHead() from @unhead/vue/client (SPA) or @unhead/vue/server (SSR); createServerHead() no longer exists source

  • BREAKING: Implicit context removed in v2 — setHeadInjectionHandler() deleted; useHead() called after an await in lifecycle hooks (e.g. onMounted) throws because Vue context is lost; wrap async data fetching before calling useHead() source

  • BREAKING: vmid and hid tag properties removed in v2 — use key for deduplication: script: [{ key: 'my-key' }] source

  • BREAKING: children tag property removed in v2 — use innerHTML instead source

  • BREAKING: body: true tag property removed in v2 — use tagPosition: 'bodyClose' instead source

  • BREAKING: useScript() no longer returns a Promise in v2 — .then() calls silently fail; use .onLoaded(() => ...) instead source

  • BREAKING: useScript() API no longer accessible directly on the instance in v2 — must use .proxy explicitly: script.proxy.myFn() not script.myFn(); code compiles but calls are lost at runtime source

  • BREAKING: stub() option and script:instance-fn hook removed from useScript() in v2 — replace with custom use() logic source

  • BREAKING: Promise inputs in useHead() no longer auto-resolved in v2 — await the promise before passing, or opt in to PromisePlugin from @unhead/vue/plugins source

  • BREAKING: TemplateParamsPlugin and AliasSortingPlugin no longer built-in in v2 — must opt in: createHead({ plugins: [TemplateParamsPlugin, AliasSortingPlugin] }) imported from @unhead/vue/plugins source

  • BREAKING: Capo.js tag sorting is now the default in v2 — breaks snapshot tests; opt out with createHead({ disableCapoSorting: true }) source

  • DEPRECATED: useServerHead(), useServerHeadSafe(), useServerSeoMeta() — use useHead(), useHeadSafe(), useSeoMeta() with import.meta.server conditionals or { mode: 'server' } option for tree-shaking

  • NEW: <Head>, <Title>, <Meta>, <Link>, <Script> template components — import from @unhead/vue/components source

  • NEW: DeprecationsPlugin from @unhead/vue/plugins — re-enables removed vmid, hid, children, body properties for gradual migration to v2 source

Also changed: @unhead/schema deprecated — use @unhead/vue/types instead · createHeadCore deprecated — use createUnhead · Default SSR tags auto-inserted in v2 (charset, viewport, html lang="en"); disable with createHead({ disableDefaults: true }) · CJS exports removed, ESM only · Vue 2 support removed · useHead() context lost after async in Vue lifecycle hooks — fetch data first, then call useHead()

Best Practices

  • Always use injectHead() from @unhead/vue instead of getActiveHead() from unhead in Vue components — injectHead() binds to the Vue component context (visible in onServerPrefetch), while getActiveHead() returns a shared cross-request instance that breaks in SSR. The maintainer confirmed this is the correct approach for Vue. source

  • Avoid calling useHead() inside watchers — each call creates a new entry rather than updating the existing one, leading to duplicate entries. Instead, pass reactive refs or computed getters directly to a single useHead() call at setup time so updates flow automatically. source

  • When useHead() must be called after async operations (e.g. inside onMounted), capture the head instance at setup time with injectHead() and pass it as { head } in the second argument — Vue's inject context is lost after await. For most cases, prefer the reactive state pattern: define useHead() once at setup with computed getters, and update a ref asynchronously. source

  • Use useHeadSafe() instead of useHead() whenever head input comes from user-provided or third-party sources — it enforces an attribute whitelist and strips script tags and event handlers, preventing XSS without requiring manual sanitization. source

  • Add the UnheadVite() plugin from @unhead/addons/vite to your Vite config for Vue apps — it tree-shakes server-only composables from the client build and transforms useSeoMeta() calls into raw useHead() calls, saving ~3kb. Nuxt configures this automatically; standalone Vue apps must opt in. source

  • Pass { mode: 'server' } to useHead() for static SEO metadata (Open Graph images, robots, schema.org) that doesn't need client-side reactivity — this strips the tags from the client bundle entirely. Similarly use { mode: 'client' } for analytics scripts to keep them out of SSR output. Caveat: titleTemplate must be included in both environments to avoid title flashing. source

  • Use tagPosition: 'bodyClose' for non-critical scripts (analytics, chat widgets) instead of head — this prevents render-blocking and improves page load performance. Use tagPriority: 'critical' | 'high' | 'low' aliases rather than raw numbers to preserve Capo.js-derived ordering weights that Unhead applies automatically. source

  • Use textContent instead of innerHTML for inline scripts and styles — textContent escapes HTML characters, preventing injection. Only use innerHTML when HTML entities are required, and sanitize the content yourself (e.g. with DOMPurify). For user-generated inline content, prefer useHeadSafe() which restricts scripts to type="application/json" only. source

  • Register TemplateParamsPlugin and define global templateParams (e.g. siteName, separator) once in your head instance setup rather than repeating them per page. These params work across all head tags — including og:title and meta descriptions — not just titleTemplate. Set %separator to a smart separator like · or —; it auto-removes when adjacent to empty content. source

  • Use InferSeoMetaPlugin to automatically derive og:title and og:description from existing title and description tags, eliminating manual duplication. Configure ogTitle with a transform function to strip the site name suffix from Open Graph titles (e.g. removing "| My Site" that titleTemplate appends). source

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open in GitHubOpen in ClawHub

Related Skills

Related by shared tags or category signals.

General

vue-skilld

No summary provided by upstream source.

Repository SourceNeeds Review
-95
harlan-zw
General

pinia-skilld

No summary provided by upstream source.

Repository SourceNeeds Review
-86
harlan-zw
General

vueuse-core-skilld

No summary provided by upstream source.

Repository SourceNeeds Review
-77
harlan-zw