unhead-vue-skilld
Skill184 starsChanged 37 days agoMITView on GitHub
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.
In this repository35 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- floating-ui-vue-skilldSkill
- formkit-core-skilldSkill
- motion-v-skilldSkill
- pinia-colada-skilldSkill
- pinia-skilldSkill
- primevue-skilldSkill
- quasar-skilldSkill
- reka-ui-skilldSkill
- shadcn-vue-skilldSkill
- slidev-cli-skilldSkill
- tanstack-ai-vue-skilldSkill
- tanstack-vue-form-skilldSkill
- tanstack-vue-query-skilldSkill
- tanstack-vue-router-skilldSkill
- tanstack-vue-store-skilldSkill
- tanstack-vue-table-skilldSkill
- tanstack-vue-virtual-skilldSkill
- tresjs-core-skilldSkill
- unovis-ts-skilldSkill
- unovis-vue-skilldSkill
- vee-validate-skilldSkill
- vitepress-skilldSkill
- vue-data-ui-skilldSkill
- vue-i18n-skilldSkill
- vue-router-skilldSkill
- vue-skilldSkill
- vue-test-utils-skilldSkill
- vuetify-skilldSkill
- vueuse-components-skilldSkill
- vueuse-core-skilldSkill
- vueuse-integrations-skilldSkill
- vueuse-math-skilldSkill
- vueuse-motion-skilldSkill
- vueuse-shared-skilldSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 48
All imported from @unhead/vue root and used inside setup():
- Very specific: line 86
Untrusted input: use useHeadSafe(); it whitelists attributes and strips scripts/handlers.
- Very specific: line 87
Head instance access in Vue: use injectHead() from @unhead/vue, not getActiveHead() from unhead.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
@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.
// 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')// 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.
Composables
All imported from @unhead/vue root and used inside setup():
<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>// 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 loadsDetails, options tables, and recipes: references/composables.md.
Critical rules
- Async context: calling
useHead()after anawaitinsideonMounted()/watchers throwsuseHead() was called without provide context. Fix, in order of preference: top-levelawaitin<script setup>; declareuseHead()once with refs/computed and update the ref later; captureconst head = injectHead()at setup time and passuseHead(input, { head }). Source: https://unhead.unjs.io/docs/vue/head/guides/core-concepts/reactivity-and-context - Never call
useHead()inside a watcher callback: each call pushes a new entry and duplicates tags. Pass the reactive value into oneuseHead()call instead. - Deduplication key is
key, nothid/vmid:meta: [{ key: 'description', name: 'description', content: '...' }]. - Inline content:
innerHTML(waschildrenin v1); body scripts usetagPosition: 'bodyClose'(wasbody: true). - Untrusted input: use
useHeadSafe(); it whitelists attributes and strips scripts/handlers. - Head instance access in Vue: use
injectHead()from@unhead/vue, notgetActiveHead()fromunhead; 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.
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.
Optional plugins at creation
Template params (%s, %separator), alias sorting (before:/after:), and Promise inputs are opt-in since v2:
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)
// 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.
Common mistakes
- Importing
createHeadfrom@unhead/vueroot (removed in v2): use/clientor/server. - Awaiting
renderSSRHead/renderDOMHead: both are synchronous in v3. useScript()return is not a Promise: useonLoaded(() => ...); 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 — SPA, SSR, streaming SSR, Options API,
<Head>component, auto-imports, defaults - references/composables.md —
useHead,useSeoMeta,useHeadSafe,useScriptusage and options - references/api-surface.md — export map, types, instance API
- references/build-plugins.md —
Unhead()bundler plugin and streaming - references/migration.md — v2 and v3 breaking changes
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

