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.
skilld-dev · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add skilld-dev/vue-ecosystem-skills --skill unhead-vue-skilld技能说明
name: unhead-vue-skilld description: "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." metadata: version: 3.1.0 generated_at: 2026-04-27 references_synced_at: 2026-04-27
unjs/unhead @unhead/vue@3.1.0
Tags: next: 3.0.0-beta.9, beta: 3.0.0-beta.12, rc: 3.0.0-rc.4
References: Docs
API Changes
This section documents version-specific API changes — prioritize recent major/minor releases.
-
BREAKING:
createHead()andcreateServerHead()removed from@unhead/vueroot 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 anawaitin lifecycle hooks (e.g.onMounted) throws because Vue context is lost; wrap async data fetching before callinguseHead()source -
BREAKING:
vmidandhidtag properties removed in v2 — usekeyfor deduplication:script: [{ key: 'my-key' }]source -
BREAKING:
childrentag property removed in v2 — useinnerHTMLinstead source -
BREAKING:
body: truetag property removed in v2 — usetagPosition: '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.proxyexplicitly:script.proxy.myFn()notscript.myFn(); code compiles but calls are lost at runtime source -
BREAKING:
stub()option andscript:instance-fnhook removed fromuseScript()in v2 — replace with customuse()logic source -
BREAKING: Promise inputs in
useHead()no longer auto-resolved in v2 — await the promise before passing, or opt in toPromisePluginfrom@unhead/vue/pluginssource -
BREAKING:
TemplateParamsPluginandAliasSortingPluginno longer built-in in v2 — must opt in:createHead({ plugins: [TemplateParamsPlugin, AliasSortingPlugin] })imported from@unhead/vue/pluginssource -
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()— useuseHead(),useHeadSafe(),useSeoMeta()withimport.meta.serverconditionals or{ mode: 'server' }option for tree-shaking -
NEW:
<Head>,<Title>,<Meta>,<Link>,<Script>template components — import from@unhead/vue/componentssource -
NEW:
DeprecationsPluginfrom@unhead/vue/plugins— re-enables removedvmid,hid,children,bodyproperties 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/vueinstead ofgetActiveHead()fromunheadin Vue components —injectHead()binds to the Vue component context (visible inonServerPrefetch), whilegetActiveHead()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 singleuseHead()call at setup time so updates flow automatically. source -
When
useHead()must be called after async operations (e.g. insideonMounted), capture the head instance at setup time withinjectHead()and pass it as{ head }in the second argument — Vue's inject context is lost afterawait. For most cases, prefer the reactive state pattern: defineuseHead()once at setup with computed getters, and update arefasynchronously. source -
Use
useHeadSafe()instead ofuseHead()whenever head input comes from user-provided or third-party sources — it enforces an attribute whi