fix(core,vue): deprecate server composables (#505)

* fix(core,vue): deprecate server composables

* doc: alert

* chore: build

* chore: build

Author: harlan-zw

docs/7.api/2.use-server-head.md docs/7.api/6.use-server-head.md

@@ -1,8 +1,11 @@
 ---
 title: useServerHead()
 description: Learn how to use server only tags.
+deprecated: true
 ---
 
+:UAlert{color="warning" variant="outline" title="Deprecated" description="The useServerHead composable is deprecated. Learn more at https://github.com/unjs/unhead/pull/505"}
+
 The `useServerHead` offers the same API as `useHead` but only works on the server.
 
 ```ts

packages/react/src/autoImports.ts

@@ -4,6 +4,5 @@ export const hookImports = {
     'useHead',
     'useSeoMeta',
     'useHeadSafe',
-    'useServerHead',
   ],
 }

packages/solid-js/src/autoImports.ts

@@ -4,6 +4,5 @@ export const hookImports = {
     'useHead',
     'useSeoMeta',
     'useHeadSafe',
-    'useServerHead',
   ],
 }

packages/svelte/src/autoImports.ts

@@ -4,6 +4,5 @@ export const autoImports = {
     'useHead',
     'useSeoMeta',
     'useHeadSafe',
-    'useServerHead',
   ],
 }

packages/unhead/src/composables.ts

@@ -43,4 +43,28 @@ export function useSeoMeta<T extends Unhead<any>>(unhead: T, input: UseSeoMetaIn
   return entry
 }
 
+/**
+ * @deprecated use `useHead` instead. Advanced use cases should tree shake using import.meta.* if statements.
+ */
+export function useServerHead<T extends Unhead<any>>(unhead: T, input: Parameters<T['push']>[0] = {}, options: Omit<HeadEntryOptions, 'mode'> = {}): ReturnType<T['push']> {
+  (options as HeadEntryOptions).mode = 'server'
+  return unhead.push(input, options) as ReturnType<T['push']>
+}
+
+/**
+ * @deprecated use `useHeadSafe` instead. Advanced use cases should tree shake using import.meta.* if statements.
+ */
+export function useServerHeadSafe<T extends Unhead<any>>(unhead: T, input: HeadSafe = {}, options: Omit<HeadEntryOptions, 'mode'> = {}): ActiveHeadEntry<HeadSafe> {
+  (options as HeadEntryOptions).mode = 'server'
+  return useHeadSafe(unhead, input, { ...options, mode: 'server' })
+}
+
+/**
+ * @deprecated use `useSeoMeta` instead. Advanced use cases should tree shake using import.meta.* if statements.
+ */
+export function useServerSeoMeta<T extends Unhead<any>>(unhead: T, input: UseSeoMetaInput = {}, options?: Omit<HeadEntryOptions, 'mode'>): ActiveHeadEntry<UseSeoMetaInput> {
+  (options as HeadEntryOptions).mode = 'server'
+  return useSeoMeta(unhead, input, { ...options, mode: 'server' })
+}
+
 export { useScript } from './scripts'

packages/unhead/src/index.ts

@@ -1,2 +1,2 @@
-export { useHead, useHeadSafe, useScript, useSeoMeta } from './composables'
+export { useHead, useHeadSafe, useScript, useSeoMeta, useServerHead, useServerHeadSafe, useServerSeoMeta } from './composables'
 export { createHeadCore } from './createHead'

packages/unhead/src/server/createHead.ts

@@ -41,7 +41,7 @@ export function createHead<T = Head>(options: CreateServerHeadOptions = {}) {
         const title = ctx.tagMap.get('title') as HeadTag | undefined
         const titleTemplate = ctx.tagMap.get('titleTemplate') as HeadTag | undefined
         const templateParams = ctx.tagMap.get('templateParams') as HeadTag | undefined
-        const payload = {
+        const payload: Head = {
           title: title?.mode === 'server' ? unhead._title : undefined,
           titleTemplate: titleTemplate?.mode === 'server' ? unhead._titleTemplate : undefined,
           templateParams: templateParams?.mode === 'server' ? unhead._templateParams : undefined,

packages/unhead/src/types/head.ts

@@ -139,6 +139,9 @@ export interface CreateClientHeadOptions extends CreateHeadOptions {
 }
 
 export interface HeadEntryOptions extends TagPosition, TagPriority, ProcessesTemplateParams, ResolvesDuplicates {
+  /**
+   * @deprecated Tree shaking should now be handled using import.meta.* if statements.
+   */
   mode?: RuntimeMode
   head?: Unhead
   /**

packages/unhead/test/unit/e2e/useServerSeoMeta.test.ts

@@ -0,0 +1,93 @@
+import { useHead, useSeoMeta } from 'unhead'
+import { renderDOMHead } from 'unhead/client'
+import { renderSSRHead } from 'unhead/server'
+import { describe, it } from 'vitest'
+import { createClientHeadWithContext, createServerHeadWithContext, useDom } from '../../util'
+
+describe('unhead e2e useServerSeoMeta', () => {
+  it('useServerSeoMeta', async () => {
+    // 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 = createServerHeadWithContext()
+    useSeoMeta(ssrHead, {
+      title: 'title from nuxt.config.ts',
+      description: 'Description from nuxt.config.ts',
+    }, {
+      tagPriority: 'low',
+    })
+    useHead(ssrHead, {
+      htmlAttrs: { lang: 'nuxt.config' },
+      script: [
+        {
+          innerHTML: 'lorem ipsum generate more lorem ipsum',
+        },
+      ],
+    }, {
+      mode: 'server',
+    })
+    // i.e App.vue
+    useSeoMeta(ssrHead, {
+      title: 'title mainpage',
+      description: 'description mainpage',
+    }, {
+      mode: 'server',
+    })
+    useHead(ssrHead, {
+      htmlAttrs: { lang: 'app.vue' },
+    }, {
+      mode: 'server',
+    })
+
+    const data = await renderSSRHead(ssrHead)
+
+    expect(data).toMatchInlineSnapshot(`
+      {
+        "bodyAttrs": "",
+        "bodyTags": "",
+        "bodyTagsOpen": "",
+        "headTags": "<title>title mainpage</title>
+      <script>lorem ipsum generate more lorem ipsum</script>
+      <meta name="description" content="description mainpage">
+      <script id="unhead:payload" type="application/json">{"title":"title mainpage"}</script>",
+        "htmlAttrs": " lang="app.vue"",
+      }
+    `)
+
+    const dom = useDom(data)
+
+    const csrHead = createClientHeadWithContext({
+      document: dom.window.document,
+    })
+    useHead(ssrHead, {
+      htmlAttrs: { lang: 'nuxt.config' },
+    }, {
+      tagPriority: 'low',
+    })
+    useSeoMeta(csrHead, {
+      title: 'Some cool reproduction repo :)',
+      description: 'Description from nuxt.config.ts',
+    }, {
+      tagPriority: 'low',
+    })
+
+    await renderDOMHead(csrHead, { document: dom.window.document })
+
+    expect(dom.serialize()).toMatchInlineSnapshot(`
+      "<!DOCTYPE html><html lang="app.vue"><head>
+      <title>title mainpage</title>
+      <script>lorem ipsum generate more lorem ipsum</script>
+      <meta name="description" content="Description from nuxt.config.ts">
+      <script id="unhead:payload" type="application/json">{"title":"title mainpage"}</script>
+      </head>
+      <body>
+
+      <div>
+      <h1>hello world</h1>
+      </div>
+
+
+
+      </body></html>"
+    `)
+  })
+})

packages/vue/src/composables.ts

@@ -86,14 +86,24 @@ export function useSeoMeta(input: UseSeoMetaInput = {}, options: UseHeadOptions
     _flatMeta: meta,
   }, options)
 }
+
+/**
+ * @deprecated use `useHead` instead.Advanced use cases should tree shake using import.meta.* if statements.
+ */
 export function useServerHead<T extends MergeHead>(input: UseHeadInput<T> = {}, options: UseHeadOptions = {}): ActiveHeadEntry<any> {
   return useHead<T>(input, { ...options, mode: 'server' })
 }
 
+/**
+ * @deprecated use `useHeadSafe` instead.Advanced use cases should tree shake using import.meta.* if statements.
+ */
 export function useServerHeadSafe(input: UseHeadSafeInput = {}, options: UseHeadOptions = {}): ActiveHeadEntry<any> {
   return useHeadSafe(input, { ...options, mode: 'server' })
 }
 
+/**
+ * @deprecated use `useSeoMeta` instead.Advanced use cases should tree shake using import.meta.* if statements.
+ */
 export function useServerSeoMeta(input: UseSeoMetaInput = {}, options?: UseHeadOptions): ActiveHeadEntry<UseSeoMetaInput> {
   return useSeoMeta(input, { ...options, mode: 'server' })
 }

packages/vue/src/legacy.ts

@@ -141,14 +141,23 @@ export function useSeoMeta(input: UseSeoMetaInput, options?: UseHeadOptions): Ac
   }
 }
 
+/**
+ * @deprecated use `useHead` instead. Advanced use cases should tree shake using import.meta.* if statements.
+ */
 export function useServerHead<T extends MergeHead>(input: UseHeadInput<T>, options: UseHeadOptions = {}): ActiveHeadEntry<any> | void {
   return useHead(input, { ...options, mode: 'server' })
 }
 
+/**
+ * @deprecated use `useHeadSafe` instead. Advanced use cases should tree shake using import.meta.* if statements.
+ */
 export function useServerHeadSafe(input: UseHeadSafeInput, options: UseHeadOptions = {}): ActiveHeadEntry<any> | void {
   return useHeadSafe(input, { ...options, mode: 'server' })
 }
 
+/**
+ * @deprecated use `useSeoMeta` instead. Advanced use cases should tree shake using import.meta.* if statements.
+ */
 export function useServerSeoMeta(input: UseSeoMetaInput, options?: UseHeadOptions): ActiveHeadEntry<any> | void {
   return useSeoMeta(input, { ...options, mode: 'server' })
 }