fix(vue): keep reactive input at useHead boundary

harlan-zw · harlan-zw · commit 82e31bc2618b · 2026-07-30T00:44:46.000+10:00
diff --git a/packages/vue/src/client.ts b/packages/vue/src/client.ts
@@ -1,16 +1,15 @@
-import type { CreateClientHeadOptions } from 'unhead/types'
-import type { UseHeadInput, VueHeadClient } from './types'
+import type { CreateClientHeadOptions, ResolvableHead } from 'unhead/types'
+import type { VueHeadClient } from './types'
 import { createHead as _createHead, createDomRenderer } from 'unhead/client'
 import { vueInstall } from './install'
-import { VueResolver } from './resolver'
 
 export { VueHeadMixin } from './VueHeadMixin'
 export { renderDOMHead } from 'unhead/client'
 
 /* @__NO_SIDE_EFFECTS__ */
-export function createHead(options: CreateClientHeadOptions = {}): VueHeadClient<UseHeadInput, boolean> {
+export function createHead(options: CreateClientHeadOptions = {}): VueHeadClient<ResolvableHead, boolean> {
   const domRenderer = createDomRenderer()
-  let head: VueHeadClient<UseHeadInput, boolean>
+  let head: VueHeadClient<ResolvableHead, boolean>
   let renderId = 0
   const debouncedRenderer = () => {
     const id = ++renderId
@@ -19,11 +18,7 @@ export function createHead(options: CreateClientHeadOptions = {}): VueHeadClient
         domRenderer(head)
     }, 0)
   }
-  head = _createHead({
-    render: debouncedRenderer,
-    ...options,
-    propResolvers: [VueResolver, ...(options.propResolvers || [])],
-  }) as VueHeadClient<UseHeadInput, boolean>
+  head = _createHead({ render: debouncedRenderer, ...options }) as VueHeadClient<ResolvableHead, boolean>
   head.install = vueInstall(head)
   return head
 }
diff --git a/packages/vue/src/legacy.ts b/packages/vue/src/legacy.ts
@@ -1,4 +1,4 @@
-import type { CreateClientHeadOptions, CreateServerHeadOptions, HeadPluginInput, SSRHeadPayload } from 'unhead/types'
+import type { CreateClientHeadOptions, CreateServerHeadOptions, HeadPluginInput, ResolvableHead, SSRHeadPayload } from 'unhead/types'
 import type { UseHeadInput, VueHeadClient } from './types'
 import { DeprecationsPlugin } from 'unhead/legacy'
 import { AliasSortingPlugin, PromisesPlugin, TemplateParamsPlugin } from 'unhead/plugins'
@@ -29,7 +29,7 @@ export const legacyPlugins: HeadPluginInput[] = [DeprecationsPlugin, PromisesPlu
  * `legacyPlugins` yourself if you still need v1/v2 tag prop compatibility.
  */
 /* @__NO_SIDE_EFFECTS__ */
-export function createHead(options: CreateClientHeadOptions = {}): VueHeadClient<UseHeadInput, boolean> {
+export function createHead(options: CreateClientHeadOptions = {}): VueHeadClient<ResolvableHead, boolean> {
   return _createClientHead({
     ...options,
     plugins: [...legacyPlugins, ...(options.plugins || [])],
diff --git a/packages/vue/src/server.ts b/packages/vue/src/server.ts
@@ -8,7 +8,7 @@ export { VueHeadMixin } from './VueHeadMixin'
 export { type PreparedTemplate, prepareTemplate, propsToString, renderSSRHead, type SSRHeadPayload, transformHtmlTemplate } from 'unhead/server'
 
 /* @__NO_SIDE_EFFECTS__ */
-export function createHead(options: Omit<CreateServerHeadOptions, 'propsResolver'> = {}): VueHeadClient<UseHeadInput, SSRHeadPayload> {
+export function createHead(options: Omit<CreateServerHeadOptions, 'propResolvers'> = {}): VueHeadClient<UseHeadInput, SSRHeadPayload> {
   const head = _createServerHead({
     ...options,
     propResolvers: [VueResolver],
diff --git a/packages/vue/src/stream/client.ts b/packages/vue/src/stream/client.ts
@@ -1,19 +1,16 @@
 import type { CreateStreamableClientHeadOptions, UnheadStreamQueue } from 'unhead/stream/client'
-import type { UseHeadInput, VueHeadClient } from '../types'
+import type { ResolvableHead } from 'unhead/types'
+import type { VueHeadClient } from '../types'
 import { createStreamableHead as _createStreamableHead } from 'unhead/stream/client'
 import { vueInstall } from '../install'
-import { VueResolver } from '../resolver'
 import { VueHeadMixin } from '../VueHeadMixin'
 
 /**
  * Creates a client head by wrapping the core instance from the iife script.
  */
 /* @__NO_SIDE_EFFECTS__ */
-export function createStreamableHead(options: CreateStreamableClientHeadOptions = {}): VueHeadClient<UseHeadInput, boolean> | undefined {
-  const head = _createStreamableHead({
-    ...options,
-    propResolvers: [VueResolver, ...(options.propResolvers || [])],
-  }) as VueHeadClient<UseHeadInput, boolean> | undefined
+export function createStreamableHead(options: CreateStreamableClientHeadOptions = {}): VueHeadClient<ResolvableHead, boolean> | undefined {
+  const head = _createStreamableHead(options) as VueHeadClient<ResolvableHead, boolean> | undefined
   if (head) {
     head.install = vueInstall(head)
   }
diff --git a/packages/vue/src/stream/server.ts b/packages/vue/src/stream/server.ts
@@ -1,6 +1,6 @@
 import type { WebStreamableHeadContext } from 'unhead/stream/server'
-import type { CreateStreamableServerHeadOptions, ResolvableHead, SSRHeadPayload } from 'unhead/types'
-import type { VueHeadClient } from '../types'
+import type { CreateStreamableServerHeadOptions, SSRHeadPayload } from 'unhead/types'
+import type { UseHeadInput, VueHeadClient } from '../types'
 import {
   createStreamableHead as _createStreamableHead,
   renderSSRHeadSuspenseChunk,
@@ -13,11 +13,11 @@ import { VueResolver } from '../resolver'
  * Vue-specific context returned by createStreamableHead.
  * Extends WebStreamableHeadContext with Vue-specific head type.
  */
-export interface VueStreamableHeadContext extends Omit<WebStreamableHeadContext<ResolvableHead>, 'head'> {
+export interface VueStreamableHeadContext extends Omit<WebStreamableHeadContext<UseHeadInput>, 'head'> {
   /**
    * The Vue head instance to use with app.use(head)
    */
-  head: VueHeadClient<any, SSRHeadPayload>
+  head: VueHeadClient<UseHeadInput, SSRHeadPayload>
 }
 
 /**
@@ -52,13 +52,13 @@ export interface VueStreamableHeadContext extends Omit<WebStreamableHeadContext<
  * ```
  */
 export function createStreamableHead(
-  options: Omit<CreateStreamableServerHeadOptions, 'propsResolver'> = {},
+  options: Omit<CreateStreamableServerHeadOptions, 'propResolvers'> = {},
 ): VueStreamableHeadContext {
   const { head } = _createStreamableHead({
     ...options,
     propResolvers: [VueResolver],
   })
-  const vueHead = head as VueHeadClient<any, SSRHeadPayload>
+  const vueHead = head as VueHeadClient<UseHeadInput, SSRHeadPayload>
   vueHead.install = vueInstall(vueHead)
 
   const flushPatch = () => {
diff --git a/packages/vue/src/types/schema.ts b/packages/vue/src/types/schema.ts
@@ -12,6 +12,7 @@ import type {
   MaybeEventFnHandlers,
   MetaFlat,
   Noscript,
+  ResolvableHead,
   ResolvableTemplateParams,
   SchemaAugmentations,
   Script,
@@ -146,4 +147,8 @@ export type UseHeadOptions = Omit<HeadEntryOptions, 'head'> & { head?: VueHeadCl
 
 export type UseHeadInput<_Deprecated = never> = ResolvableValue<ReactiveHead>
 export type UseSeoMetaInput = ResolvableProperties<MetaFlat> & { title?: ReactiveHead['title'], titleTemplate?: ReactiveHead['titleTemplate'] }
-export type VueHeadClient<I = UseHeadInput, R = unknown> = Unhead<I, R> & Plugin
+/**
+ * Client heads accept core-resolvable input by default. Pass Vue reactive input
+ * through useHead(), which owns dependency tracking and lifecycle cleanup.
+ */
+export type VueHeadClient<I = ResolvableHead, R = unknown> = Unhead<I, R> & Plugin
diff --git a/packages/vue/test/unit/dom/pushResolver.test.ts b/packages/vue/test/unit/dom/pushResolver.test.ts
diff --git a/packages/vue/test/unit/e2e/basic.test.ts b/packages/vue/test/unit/e2e/basic.test.ts
@@ -141,7 +141,7 @@ describe('vue e2e', () => {
   })
 
   it('hydration breaking', async () => {
-    const schema = <ReactiveHead> {
+    const schema = {
       title: 'My amazing site',
       htmlAttrs: {
         class: 'layout-default',
@@ -179,7 +179,7 @@ describe('vue e2e', () => {
           charset: 'utf-8',
         },
       ],
-    }
+    } satisfies ReactiveHead
     // scenario: we are injecting root head schema which will not have a hydration step,
     // but we are also injecting a child head schema which will have a hydration step
     const ssrHead = await ssrVueAppWithUnhead(() => {
diff --git a/packages/vue/test/unit/e2e/charset.test.ts b/packages/vue/test/unit/e2e/charset.test.ts
@@ -8,27 +8,27 @@ import { csrVueAppWithUnhead, ssrVueAppWithUnhead } from '../../util'
 
 describe('vue e2e charset', () => {
   it('ssr / csr hydration', async () => {
-    const AppSchema: ReactiveHead = {
+    const AppSchema = {
       title: 'My app',
       meta: [
         {
           charset: 'utf-8',
         },
       ],
-    }
+    } satisfies ReactiveHead
 
-    const IndexSchema: ReactiveHead = {
+    const IndexSchema = {
       title: 'Home page',
       meta: [
         {
           charset: () => 'utf-8',
         },
       ],
-    }
+    } satisfies ReactiveHead
 
-    const AboutSchema: ReactiveHead = {
+    const AboutSchema = {
       title: 'About page',
-    }
+    } satisfies ReactiveHead
 
     // ssr render on the index page
     const ssrHead = await ssrVueAppWithUnhead(() => {
diff --git a/packages/vue/test/unit/e2e/keys.test.ts b/packages/vue/test/unit/e2e/keys.test.ts
@@ -12,13 +12,13 @@ const SPACE_RE = / /
 
 describe('vue e2e keys', () => {
   it('ssr / csr hydration', async () => {
-    const IndexSchema: ReactiveHead = {
+    const IndexSchema = {
       link: [{ rel: 'icon', href: '/page-index.ico', key: 'main-icon' }],
-    }
+    } satisfies ReactiveHead
 
-    const AboutSchema: ReactiveHead = {
+    const AboutSchema = {
       link: [{ rel: 'icon', href: '/page-about.ico', key: 'main-icon' }],
-    }
+    } satisfies ReactiveHead
 
     // ssr render on the index page
     const ssrHead = createServerHead({
diff --git a/packages/vue/test/unit/types.test.ts b/packages/vue/test/unit/types.test.ts
@@ -1,8 +1,11 @@
 import type { SSRHeadPayload } from 'unhead/types'
 import type { RawInput, SerializableHead } from '../../src/'
+import type { injectHead } from '../../src/composables'
 import { createHead } from '@unhead/vue/client'
 import { createHead as createServerHead } from '@unhead/vue/server'
-import { computed } from 'vue'
+import { createStreamableHead } from '@unhead/vue/stream/client'
+import { createStreamableHead as createStreamableServerHead } from '@unhead/vue/stream/server'
+import { computed, ref } from 'vue'
 import { useHead, useHeadSafe } from '../../src/composables'
 
 describe('types', () => {
@@ -137,6 +140,44 @@ describe('types', () => {
     // @ts-expect-error server render() should not be assignable to boolean
     serverHead.render() satisfies boolean
   })
+  it('keeps Vue reactivity at the useHead interface', () => {
+    const clientHead = createHead()
+    const title = ref('Reactive title')
+
+    useHead({ title }, { head: clientHead })
+    useHead(computed(() => ({ title: title.value })), { head: clientHead })
+    clientHead.push({ title: () => title.value })
+
+    // @ts-expect-error Vue refs require useHead() on the client
+    clientHead.push({ title })
+    // @ts-expect-error Root Vue refs require useHead() on the client
+    clientHead.push(ref({ title: 'Reactive title' }))
+    // @ts-expect-error Vue computed entries require useHead() on the client
+    clientHead.push(computed(() => ({ title: title.value })))
+
+    // @ts-expect-error Injected client heads expose the same raw input contract
+    const injectedInput: Parameters<ReturnType<typeof injectHead>['push']>[0] = { title }
+    void injectedInput
+
+    const streamHead = createStreamableHead()
+    streamHead?.push({ title: () => title.value })
+    // @ts-expect-error Vue refs require useHead() on the streaming client
+    streamHead?.push({ title })
+
+    const serverHead = createServerHead()
+    serverHead.push({ title })
+    serverHead.push(computed(() => ({ title: title.value })))
+    // @ts-expect-error Vue server heads own the Vue resolver chain
+    createServerHead({ propResolvers: [] })
+
+    const { head: streamServerHead } = createStreamableServerHead()
+    streamServerHead.push({ title })
+    streamServerHead.push(computed(() => ({ title: title.value })))
+    // @ts-expect-error Stream server heads retain a concrete input schema
+    streamServerHead.push({ invalid: true })
+    // @ts-expect-error Vue stream server heads own the Vue resolver chain
+    createStreamableServerHead({ propResolvers: [] })
+  })
   it('types nuxt core', () => {
     const payloadURL = 'test'
     const link: RawInput<'link'> = process.env.NUXT_JSON_PAYLOADS
diff --git a/packages/vue/vitest.config.ts b/packages/vue/vitest.config.ts
@@ -11,6 +11,8 @@ export default defineProject({
       '@unhead/bundler/framework': resolve(__dirname, '../bundler/src/unplugin/framework.ts'),
       '@unhead/bundler': resolve(__dirname, '../bundler/src'),
       '@unhead/schema-org/vue': resolve(__dirname, '../schema-org/src/vue/index.ts'),
+      '@unhead/vue/stream/server': resolve(__dirname, 'src/stream/server.ts'),
+      '@unhead/vue/stream/client': resolve(__dirname, 'src/stream/client.ts'),
       '@unhead/vue/server': resolve(__dirname, 'src/server.ts'),
       '@unhead/vue/client': resolve(__dirname, 'src/client.ts'),
       '@unhead/vue': resolve(__dirname, 'src/index.ts'),
diff --git a/tsconfig.json b/tsconfig.json
@@ -27,6 +27,8 @@
       "@unhead/vue": ["./packages/vue/src/index"],
       "@unhead/vue/client": ["./packages/vue/src/client"],
       "@unhead/vue/server": ["./packages/vue/src/server"],
+      "@unhead/vue/stream/client": ["./packages/vue/src/stream/client"],
+      "@unhead/vue/stream/server": ["./packages/vue/src/stream/server"],
       "@unhead/bundler": ["./packages/bundler/src/index"],
       "@unhead/bundler/vite": ["./packages/bundler/src/unplugin/vite"],
       "@unhead/bundler/framework": ["./packages/bundler/src/unplugin/framework"],
