feat(react): simplified API, useScript()

Author: harlan-zw

packages/react/build.config.ts

@@ -8,6 +8,7 @@ export default defineBuildConfig({
     { input: 'src/index', name: 'index' },
     { input: 'src/server', name: 'server' },
     { input: 'src/client', name: 'client' },
-    { input: 'src/types/index', name: 'types' },
+    { input: 'src/utils', name: 'utils' },
+    { input: 'src/plugins', name: 'plugins' },
   ],
 })

packages/react/package.json

@@ -28,9 +28,13 @@
       "types": "./dist/client.d.ts",
       "import": "./dist/client.mjs"
     },
-    "./types": {
-      "types": "./dist/types.d.ts",
-      "import": "./dist/types.mjs"
+    "./utils": {
+      "types": "./dist/utils.d.ts",
+      "import": "./dist/utils.mjs"
+    },
+    "./plugins": {
+      "types": "./dist/plugins.d.ts",
+      "import": "./dist/plugins.mjs"
     }
   },
   "main": "dist/index.mjs",
@@ -44,16 +48,20 @@
       "client": [
         "dist/client"
       ],
-      "types": [
-        "dist/types"
+      "plugins": [
+        "dist/plugins"
+      ],
+      "utils": [
+        "dist/utils"
       ]
     }
   },
   "files": [
     "client.d.ts",
     "dist",
+    "plugins.d.ts",
     "server.d.ts",
-    "types.d.ts"
+    "utils.d.ts"
   ],
   "scripts": {
     "build": "unbuild .",

packages/react/plugins.d.ts

@@ -0,0 +1 @@
+export * from './dist/plugins'

packages/react/src/client.ts

@@ -1,27 +1,18 @@
 import type { ReactNode } from 'react'
-import type { CreateClientHeadOptions, MergeHead } from 'unhead/types'
-import type { MaybeComputedRef, ReactiveHead, ReactUnhead } from './types'
+import type { CreateClientHeadOptions, Unhead } from 'unhead/types'
 import { createElement } from 'react'
 import { createHead as _createHead, createDebouncedFn, renderDOMHead } from 'unhead/client'
 import { UnheadContext } from './context'
 
 export { renderDOMHead } from 'unhead/client'
 
-export function createHead<T extends MergeHead>(options: Omit<CreateClientHeadOptions, 'propResolvers'> = {}): ReactUnhead<T> {
-  const head = _createHead<MaybeComputedRef<ReactiveHead<T>>>({
+export function createHead(options: CreateClientHeadOptions = {}): Unhead {
+  const head = _createHead({
     domOptions: {
       render: createDebouncedFn(() => renderDOMHead(head), fn => setTimeout(fn, 0)),
     },
     ...options,
-    propResolvers: [
-      (_: string, r: any) => {
-        if (typeof r === 'object' && 'current' in r) {
-          return r.current
-        }
-        return r
-      },
-    ],
-  }) as ReactUnhead<T>
+  })
   return head
 }
 

packages/react/src/composables.ts

@@ -1,53 +1,111 @@
-import type { ActiveHeadEntry, HeadEntryOptions, HeadSafe, MergeHead } from 'unhead/types'
-import type { UseHeadInput, UseSeoMetaInput } from './types'
-import { useContext, useEffect } from 'react'
-import { FlatMetaPlugin, SafeInputPlugin } from 'unhead/plugins'
+import type {
+  ActiveHeadEntry,
+  HeadEntryOptions,
+  HeadSafe,
+  Unhead,
+  UseHeadInput,
+  UseScriptInput,
+  UseScriptOptions,
+  UseScriptReturn,
+  UseSeoMetaInput,
+} from 'unhead/types'
+import { useContext, useEffect, useState } from 'react'
+import { useHead as baseHead, useHeadSafe as baseHeadSafe, useSeoMeta as baseSeoMeta, useScript as baseUseScript } from 'unhead'
 import { UnheadContext } from './context'
 
-export function useUnhead() {
+export function useUnhead(): Unhead {
   // fallback to react context
-  const instance = useContext(UnheadContext)
+  const instance = useContext<Unhead | null>(UnheadContext)
   if (!instance) {
     throw new Error('useHead() was called without provide context.')
   }
   return instance
 }
 
-export function useHead<T extends MergeHead>(input: UseHeadInput<T>, options: HeadEntryOptions = {}): ActiveHeadEntry<UseHeadInput<T>> {
-  const head = options.head || useUnhead()
-  // @ts-expect-error untyped
-  const entry = head.push(input, options)
-
+function withSideEffects<T extends ActiveHeadEntry<any>>(input: any, options: any, fn: any): T {
+  const unhead = options.head || useUnhead()
+  const [entry] = useState<T>(() => fn(unhead, input, options))
   useEffect(() => {
-    // @ts-expect-error untyped
     entry.patch(input)
   }, [input])
-
   useEffect(() => {
     return () => {
-      entry?.dispose()
+      // unmount
+      entry.dispose()
     }
   }, [])
-
-  // @ts-expect-error untyped
   return entry
 }
 
-export function useHeadSafe(input: HeadSafe, options: HeadEntryOptions = {}): ActiveHeadEntry<HeadSafe> {
-  const head = options.head || useUnhead()
-  head.use(SafeInputPlugin)
-  options._safe = true
-  // @ts-expect-error untyped
-  return useHead(input, options)
+export function useHead(input: UseHeadInput = {}, options: HeadEntryOptions = {}): ActiveHeadEntry<UseHeadInput> {
+  return withSideEffects(input, options, baseHead)
 }
 
-export function useSeoMeta(input: UseSeoMetaInput, options: HeadEntryOptions = {}): ActiveHeadEntry<any> {
-  const head = options.head || useUnhead()
-  head.use(FlatMetaPlugin)
-  const { title, titleTemplate, ...meta } = input
-  return useHead({
-    title,
-    titleTemplate,
-    _flatMeta: meta,
-  }, options)
+export function useHeadSafe(input: HeadSafe = {}, options: HeadEntryOptions = {}): ActiveHeadEntry<HeadSafe> {
+  return withSideEffects<ActiveHeadEntry<HeadSafe>>(input, options, baseHeadSafe)
+}
+
+export function useSeoMeta(input: UseSeoMetaInput = {}, options: HeadEntryOptions = {}): ActiveHeadEntry<UseSeoMetaInput> {
+  return withSideEffects<ActiveHeadEntry<UseSeoMetaInput>>(input, options, baseSeoMeta)
+}
+
+export function useScript<T extends Record<symbol | string, any> = Record<symbol | string, any>>(_input: UseScriptInput, _options?: UseScriptOptions<T>): UseScriptReturn<T> {
+  const input = (typeof _input === 'string' ? { src: _input } : _input) as UseScriptInput
+  const options = _options || {} as UseScriptOptions<T>
+  const head = options?.head || useUnhead()
+  options.head = head
+
+  const mountCbs: (() => void)[] = []
+  let isMounted = false
+  useEffect(() => {
+    isMounted = true
+    mountCbs.forEach(i => i())
+    return () => {
+      isMounted = false
+    }
+  }, [])
+
+  if (typeof options.trigger === 'undefined') {
+    options.trigger = (load) => {
+      if (isMounted) {
+        load()
+      }
+      else {
+        mountCbs.push(load)
+      }
+    }
+  }
+  // @ts-expect-error untyped
+  const script = baseUseScript(head, input as BaseUseScriptInput, options)
+  // Note: we don't remove scripts on unmount as it's not a common use case and reloading the script may be expensive
+  const sideEffects: (() => void)[] = []
+  useEffect(() => {
+    return () => {
+      script._triggerAbortController?.abort()
+      sideEffects.forEach(i => i())
+    }
+  }, [])
+  const _registerCb = (key: 'loaded' | 'error', cb: any) => {
+    let i: number | null
+    const destroy = () => {
+      // avoid removing the wrong callback
+      if (i) {
+        script._cbs[key]?.splice(i - 1, 1)
+        i = null
+      }
+    }
+    mountCbs.push(() => {
+      if (!script._cbs[key]) {
+        cb(script.instance)
+        return () => {}
+      }
+      i = script._cbs[key].push(cb)
+      sideEffects.push(destroy)
+      return destroy
+    })
+  }
+  // if we have a scope we should make these callbacks reactive
+  script.onLoaded = (cb: (instance: T) => void | Promise<void>) => _registerCb('loaded', cb)
+  script.onError = (cb: (err?: Error) => void | Promise<void>) => _registerCb('error', cb)
+  return script
 }

packages/react/src/context.ts

@@ -1,4 +1,4 @@
 import type { Unhead } from 'unhead/types'
 import { createContext } from 'react'
 
-export const UnheadContext = createContext<Unhead<any> | null>(null)
+export const UnheadContext = createContext<Unhead | null>(null)

packages/react/src/index.ts

@@ -1,3 +1,3 @@
 export { hookImports } from './autoImports'
 export { Head } from './components'
-export { useHead, useHeadSafe, useSeoMeta, useUnhead } from './composables'
+export { useHead, useHeadSafe, useScript, useSeoMeta, useUnhead } from './composables'

packages/react/src/plugins.ts

@@ -0,0 +1 @@
+export * from 'unhead/plugins'

packages/react/src/server.ts

@@ -1,26 +1,10 @@
 import type { ReactNode } from 'react'
-import type { CreateServerHeadOptions, MergeHead } from 'unhead/types'
-import type { MaybeComputedRef, ReactiveHead, ReactUnhead } from './types'
+import type { Unhead } from 'unhead/types'
 import { createElement } from 'react'
-import { createHead as _createHead } from 'unhead/server'
 import { UnheadContext } from './context'
 
-export { extractUnheadInputFromHtml, renderSSRHead, type SSRHeadPayload, transformHtmlTemplate } from 'unhead/server'
+export { createHead, extractUnheadInputFromHtml, renderSSRHead, type SSRHeadPayload, transformHtmlTemplate } from 'unhead/server'
 
-export function createHead<T extends MergeHead>(options: Omit<CreateServerHeadOptions, 'propResolvers'> = {}): ReactUnhead<T> {
-  return _createHead<MaybeComputedRef<ReactiveHead<T>>>({
-    ...options,
-    propResolvers: [
-      (_: string, r: any) => {
-        if (typeof r === 'object' && 'current' in r) {
-          return r.current
-        }
-        return r
-      },
-    ],
-  }) as ReactUnhead<T>
-}
-
-export function UnheadProvider({ children, value }: { children: ReactNode, value: ReturnType<typeof createHead> }) {
+export function UnheadProvider({ children, value }: { children: ReactNode, value: Unhead }) {
   return createElement(UnheadContext.Provider, { value }, children)
 }