fix: switch to HookableCore (#631)

harlan-zw · web-flow · commit cc794995d0ca · 2026-01-04T20:38:25.000+11:00
diff --git a/packages/unhead/src/types/head.ts b/packages/unhead/src/types/head.ts
@@ -1,5 +1,5 @@
-import type { Hookable, NestedHooks } from 'hookable'
-import type { HeadHooks } from './hooks'
+import type { HookableCore } from 'hookable'
+import type { ClientHeadHooks, CoreHeadHooks, HeadHooks, ServerHeadHooks } from './hooks'
 import type { ResolvableHead } from './schema'
 import type { HeadTag, ProcessesTemplateParams, ResolvesDuplicates, TagPosition, TagPriority, TemplateParams } from './tags'
 
@@ -91,10 +91,10 @@ export interface ActiveHeadEntry<Input> {
 
 export type PropResolver = (key?: string, value?: any, tag?: HeadTag) => any
 
-export interface CreateHeadOptions {
+export interface CreateHeadOptions<Hooks extends CoreHeadHooks = HeadHooks> {
   document?: Document
   plugins?: HeadPluginInput[]
-  hooks?: NestedHooks<HeadHooks>
+  hooks?: Partial<Hooks>
   /**
    * Initial head input that should be added.
    *
@@ -111,7 +111,7 @@ export interface CreateHeadOptions {
   _tagWeight?: (tag: HeadTag) => number
 }
 
-export interface CreateServerHeadOptions extends CreateHeadOptions {
+export interface CreateServerHeadOptions extends CreateHeadOptions<ServerHeadHooks> {
   /**
    * Should default important tags be skipped.
    *
@@ -123,7 +123,7 @@ export interface CreateServerHeadOptions extends CreateHeadOptions {
   disableDefaults?: boolean
 }
 
-export interface CreateClientHeadOptions extends CreateHeadOptions {
+export interface CreateClientHeadOptions extends CreateHeadOptions<ClientHeadHooks> {
   /**
    * Custom render function for DOM updates.
    */
@@ -142,9 +142,9 @@ export interface HeadEntryOptions extends TagPosition, TagPriority, ProcessesTem
   _index?: number
 }
 
-export type HeadRenderer<T = unknown> = (head: Unhead<any>) => T
+export type HeadRenderer<T = unknown, H extends CoreHeadHooks = CoreHeadHooks> = (head: Unhead<any, any, H>) => T
 
-export interface Unhead<Input = ResolvableHead, RenderResult = unknown> {
+export interface Unhead<Input = ResolvableHead, RenderResult = unknown, Hooks extends CoreHeadHooks = HeadHooks> {
   /**
    * Render the head tags using the configured renderer.
    */
@@ -164,7 +164,7 @@ export interface Unhead<Input = ResolvableHead, RenderResult = unknown> {
   /**
    * Exposed hooks for easier extension.
    */
-  hooks: Hookable<HeadHooks>
+  hooks: HookableCore<Hooks>
   /**
    * Resolved options
    */
diff --git a/packages/unhead/src/types/hooks.ts b/packages/unhead/src/types/hooks.ts
@@ -34,24 +34,29 @@ export interface SSRRenderContext { tags: HeadTag[], html: SSRHeadPayload }
 
 interface TagResolveContext { tagMap: Map<string, HeadTag>, tags: HeadTag[] }
 
-export interface HeadHooks {
+export interface CoreHeadHooks {
   'entries:updated': (ctx: Unhead<any>) => HookResult
   'entries:resolve': (ctx: EntryResolveCtx<any>) => SyncHookResult
   'entries:normalize': (ctx: { tags: HeadTag[], entry: HeadEntry<any> }) => SyncHookResult
   'tag:normalise': (ctx: { tag: HeadTag, entry: HeadEntry<any>, resolvedOptions: CreateClientHeadOptions }) => SyncHookResult
   'tags:beforeResolve': (ctx: TagResolveContext) => SyncHookResult
   'tags:resolve': (ctx: TagResolveContext) => SyncHookResult
   'tags:afterResolve': (ctx: TagResolveContext) => SyncHookResult
+  'script:updated': (ctx: { script: ScriptInstance<any> }) => void | Promise<void>
+}
 
-  // client
+export interface DOMHeadHooks {
   'dom:beforeRender': (ctx: DomBeforeRenderCtx) => SyncHookResult
   'dom:renderTag': (ctx: DomRenderTagContext, document: Document, track: (id: string, scope: string, fn: () => void) => void) => HookResult
   'dom:rendered': (ctx: { renders: DomRenderTagContext[] }) => HookResult
+}
 
-  // server
+export interface SSRHeadHooks {
   'ssr:beforeRender': (ctx: ShouldRenderContext) => HookResult
   'ssr:render': (ctx: { tags: HeadTag[] }) => HookResult
   'ssr:rendered': (ctx: SSRRenderContext) => HookResult
-
-  'script:updated': (ctx: { script: ScriptInstance<any> }) => void | Promise<void>
 }
+
+export type ClientHeadHooks = CoreHeadHooks & DOMHeadHooks
+export type ServerHeadHooks = CoreHeadHooks & SSRHeadHooks
+export type HeadHooks = CoreHeadHooks & DOMHeadHooks & SSRHeadHooks
diff --git a/packages/unhead/src/unhead.ts b/packages/unhead/src/unhead.ts
@@ -1,24 +1,30 @@
 import type {
   ActiveHeadEntry,
+  CoreHeadHooks,
   CreateHeadOptions,
   HeadEntry,
   HeadEntryOptions,
-  HeadHooks,
   HeadPlugin,
   HeadPluginInput,
   HeadRenderer,
   ResolvableHead,
   Unhead,
 } from './types'
-import { createHooks } from 'hookable'
+import { HookableCore } from 'hookable'
 
-export function registerPlugin(head: Unhead<any, any>, p: HeadPluginInput) {
+function addHooks<T extends Record<string, any>>(hooks: HookableCore<T>, configHooks: Partial<T>) {
+  for (const key in configHooks) {
+    hooks.hook(key as any, configHooks[key] as any)
+  }
+}
+
+export function registerPlugin(head: Unhead<any, any, any>, p: HeadPluginInput) {
   const plugin = (typeof p === 'function' ? p(head) : p)
   const key = plugin.key || String(head.plugins.size + 1)
   const exists = head.plugins.get(key)
   if (!exists) {
     head.plugins.set(key, plugin)
-    head.hooks.addHooks(plugin.hooks || {})
+    addHooks(head.hooks, plugin.hooks || {})
   }
 }
 
@@ -27,14 +33,14 @@ export function registerPlugin(head: Unhead<any, any>, p: HeadPluginInput) {
  * and does not register DOM plugins.
  */
 /* @__NO_SIDE_EFFECTS__ */
-export function createUnhead<T = ResolvableHead, R = unknown>(renderer: HeadRenderer<R>, resolvedOptions: CreateHeadOptions = {}): Unhead<T, R> {
-  const hooks = createHooks<HeadHooks>()
-  hooks.addHooks(resolvedOptions.hooks || {})
+export function createUnhead<T = ResolvableHead, R = unknown, H extends CoreHeadHooks = CoreHeadHooks>(renderer: HeadRenderer<R, H>, resolvedOptions: CreateHeadOptions<H> = {}): Unhead<T, R, H> {
+  const hooks = new HookableCore<H>()
+  addHooks(hooks, resolvedOptions.hooks || {})
   const ssr = !resolvedOptions.document
 
   const entries: Map<number, HeadEntry<T>> = new Map()
   const plugins: Map<string, HeadPlugin> = new Map()
-  const head: Unhead<T, R> = {
+  const head: Unhead<T, R, H> = {
     _entryCount: 1, // 0 is reserved for internal use
     plugins,
     resolvedOptions,
diff --git a/packages/unhead/test/unit/hooks/delay-dom.test.ts b/packages/unhead/test/unit/hooks/delay-dom.test.ts
@@ -7,10 +7,8 @@ describe('hooks', () => {
     let isDomPaused = true
     const head = useDOMHead({
       hooks: {
-        dom: {
-          beforeRender(ctx) {
-            ctx.shouldRender = !isDomPaused
-          },
+        'dom:beforeRender': function (ctx) {
+          ctx.shouldRender = !isDomPaused
         },
       },
     })
