unhead-vue-skilld

@unhead/vue 3.4.1

Vue 3 向けのフルスタック <head> 管理機能です。ESM 専用（"type": "module"）で、CJS はサポートしていません。 ピア依存関係：vue >= 3.5.18、オプションの依存関係：vite >= 6.4.2、webpack >= 5.0.0（出典：package.json:138-150）。 Vue 2：サポート対象外です。@unhead/vue@^1 を使用してください。 Nuxt：Unhead はすでに統合されています。手動でインストールしたり、セットアップしたりしないでください。

セットアップ（必須）

@unhead/vue をインストールし、head インスタンスを作成して、Vue プラグインとして登録します。createHead はパッケージのルートではなく、サブパスのエクスポートからインポートします。

// 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)
}

SSR テンプレートの完全な接続、ストリーミング SSR、Options API、自動インポートについては、references/setup.md を参照してください。

コンポーザブル

すべて @unhead/vue のルートからインポートし、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 loads

詳細、オプションの表、レシピについては、references/composables.md を参照してください。

重要なルール

1. 非同期コンテキスト：onMounted()／ウォッチャー内で await の後に useHead() を呼び出すと、useHead() was called without provide context がスローされます。優先順に、<script setup> 内のトップレベル await を使用する、ref／computed を使って useHead() を一度だけ宣言し後から ref を更新する、セットアップ時に const head = injectHead() を取得して useHead(input, { head }) に渡す、のいずれかで対処してください。出典：https://unhead.unjs.io/docs/vue/head/guides/core-concepts/reactivity-and-context
2. ウォッチャーのコールバック内で useHead() を呼び出さないでください：呼び出すたびに新しいエントリーが追加され、タグが重複します。リアクティブな値を 1 回の useHead() 呼び出しに渡してください。
3. 重複排除キーは key です。hid／vmid ではありません：meta: [{ key: 'description', name: 'description', content: '...' }]。
4. インラインコンテンツ：innerHTML を使用します（v1 では children）。body スクリプトには tagPosition: 'bodyClose' を使用します（以前は body: true）。
5. 信頼できない入力：useHeadSafe() を使用してください。属性を許可リストで制限し、スクリプト／ハンドラーを除去します。
6. Vue での head インスタンスへのアクセス：unhead の getActiveHead() ではなく、@unhead/vue の injectHead() を使用してください。コンポーネントコンテキスト（例：onServerPrefetch）にバインドするのは前者だけです。

3.4.1 で非推奨（現在は存在しますが、削除予定です）

エクスポート	ステータス	置き換え先
useServerHead、useServerHeadSafe、useServerSeoMeta	非推奨（dist/index.d.ts:26-30）	useHead／useHeadSafe／useSeoMeta
@unhead/vue/legacy（createHead、createServerHead、legacyPlugins）	非推奨、v4 で削除（dist/legacy.d.ts:14-30）	@unhead/vue/client／@unhead/vue/server
resolveUnrefHeadInput	非推奨（dist/utils.d.ts:9）	unhead/utils の resolveTags(head)
@unhead/vue/stream/vite の unheadVuePlugin	非推奨（dist/stream/vite.d.ts:8）	@unhead/vue/bundler の Unhead({ streaming: true }).vite()
MergeHead 型	非推奨（dist/types.d.ts:66）	VueHeadClient のジェネリクス

v3 で削除済み（コンパイルできません）：DeprecationsPlugin、setHeadInjectionHandler、createHeadCore、{ mode: 'server' | 'client' } エントリーオプション、init／dom:renderTag／dom:rendered フック、headEntries()（[...head.entries.values()] を使用してください）。 移行の詳細については、references/migration.md を参照してください。

エクスポートマップ

サブパス	用途
@unhead/vue	コンポーザブル：useHead、useSeoMeta、useHeadSafe、useScript、injectHead、VueHeadMixin、unheadVueComposablesImports、createUnhead、defineLink、defineScript
@unhead/vue/client	createHead()（SPA／ハイドレーション）、renderDOMHead、VueHeadMixin
@unhead/vue/server	createHead()（SSR）、renderSSRHead、transformHtmlTemplate、propsToString
@unhead/vue/components	<Head> コンポーネント
@unhead/vue/plugins	unhead/plugins を再エクスポート（TemplateParamsPlugin、AliasSortingPlugin、PromisePlugin、InferSeoMetaPlugin、ValidatePlugin、...）
@unhead/vue/bundler	vite／webpack／rspack／rollup 向けの統合ビルドプラグイン Unhead()
@unhead/vue/vite	Vite 専用の Unhead()。/bundler を推奨します
@unhead/vue/stream/server、/stream/client	ストリーミング SSR 用の createStreamableHead()
@unhead/vue/types、/utils、/scripts、/legacy	型、ユーティリティ、スクリプトの型、レガシー用シム

シグネチャと型の全容：references/api-surface.md。

作成時に指定するオプションプラグイン

テンプレートパラメーター（%s、%separator）、エイリアスの並べ替え（before:／after:）、Promise 入力は、v2 以降はオプトインです。

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

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

TemplateParamsPlugin がない場合、%siteName プレースホルダーはそのまま表示されます。

ビルドプラグイン（単独の Vue アプリに推奨）

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

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

クライアントバンドルからサーバー専用のコンポーザブルをツリーシェイクし、useSeoMeta() を useHead() に変換し（約3kb）、開発時には ValidatePlugin を挿入します。オプションの表と webpack に関する注意事項：references/build-plugins.md。

よくある間違い

• ルートの @unhead/vue から createHead をインポートする（v2 で削除）：/client または /server を使用します。
• renderSSRHead／renderDOMHead を await する：どちらも v3 では同期処理です。
• useScript() の戻り値は Promise ではありません：onLoaded(() => ...) を使用し、API は .proxy 経由で呼び出します。
• メタタグには content が必要です：{ name: 'description', content: null } とするとタグが削除されます。
• フォントのプリロードには crossorigin が必要です：{ rel: 'preload', as: 'font', href: '/f.woff2', crossorigin: 'anonymous' }。

参考資料

• references/setup.md — SPA、SSR、ストリーミング SSR、Options API、<Head> コンポーネント、自動インポート、デフォルト値
• references/composables.md — useHead、useSeoMeta、useHeadSafe、useScript の使い方とオプション
• references/api-surface.md — エクスポートマップ、型、インスタンス API
• references/build-plugins.md — Unhead() バンドラープラグインとストリーミング
• references/migration.md — v2 と v3 の破壊的変更