Hooks are how modules cooperate without importing each other. Mutating nuxt.options only affects modules that run after you; a hook lets you react to something that has not happened yet, and lets someone else react to something you do. A senior answer names the family a hook belongs to before naming the hook, because the three families live in three different processes and mixing them up is the most common module bug after the build/runtime boundary itself.

Know

• Powered by unjs/hookable. nuxt.hook(name, fn) registers, nuxt.callHook(name, ...args) runs. Listeners run serially in registration order and each one is awaited; callHookParallel runs them with Promise.all when order does not matter; hookOnce unregisters after the first call; hook() returns an unsubscribe function, which is what you keep when a module registers something conditionally or in a dev-only path.
• callHookWith lets you wrap the whole set of listeners (Nuxt uses it for timings and error capture). addHooks(obj) registers a map at once — that is exactly what the hooks field of defineNuxtModule does, before setup runs.
• Three families, three processes:
  1. Build hooks on nuxt — nuxt.hook('pages:extend', …). Node, during build. Only modules and nuxt.config's hooks key can use them.
  2. App runtime hooks on nuxtApp — nuxtApp.hook('page:finish', …) from a Nuxt plugin. Browser and SSR. Examples: app:created, vue:setup, app:rendered (server), app:beforeMount, app:mounted, app:suspense:resolve, page:start, page:finish, page:loading:start, page:loading:end, link:prefetch, app:error, vue:error, app:data:refresh, app:manifest:update, dev:ssr-logs.
  3. Nitro runtime hooks on nitroApp.hooks — from a Nitro plugin registered with addNitroPlugin. Server only, per request: request, beforeResponse, afterResponse, render:html, render:response, error, close.
• Goal → build hook cheat sheet:

• Declare your own hooks by augmenting NuxtHooks (build), RuntimeNuxtHooks in #app (app runtime) or NitroRuntimeHooks (Nitro), then calling them with nuxt.callHook / nuxtApp.callHook / nitroApp.hooks.callHook. This is how @nuxtjs/i18n exposes i18n:registerModule and how Tailwind exposes tailwindcss:config — and it is the right way to let a downstream team layer contribute to your toolkit without depending on your internals.
• hooks in nuxt.config is the consumer's version of the same mechanism. A team layer can therefore react to your custom hooks without writing a module at all.
• Nuxt 5 changes the return type. Nuxt 5 The upgrade guide lists this as Non-Async callHook: with hookable v6, callHook may return void instead of always returning Promise<void>, so nuxt.callHook('x').then(…) breaks on undefined. The documented migration is to await the call, which is correct in both versions.

How it works

Reacting, mutating and cleaning up in one module:

import { addTemplate, defineNuxtModule, updateTemplates, useLogger } from '@nuxt/kit'
import type { ToolkitRegistry } from './registry'

export default defineNuxtModule({
  meta: { name: 'nuxt-team-toolkit', configKey: 'toolkit' },
  setup (_options, nuxt) {
    const logger = useLogger('nuxt-team-toolkit')
    const registry: ToolkitRegistry = { entries: [], add (entry) { this.entries.push(entry) } }

    addTemplate({
      filename: 'toolkit/registry.mjs',
      getContents: () => `export const entries = ${JSON.stringify(registry.entries)}`,
    })

    // runs after every module: nuxt.options now reflects all of them
    nuxt.hook('modules:done', async () => {
      await nuxt.callHook('toolkit:extend', registry)
    })

    // regenerate only our own templates when the watched directory changes
    nuxt.hook('builder:watch', async (_event, path) => {
      if (!path.includes('toolkit-routes/')) { return }
      await updateTemplates({ filter: t => t.filename.startsWith('toolkit/') })
    })

    // one-shot: report once, not on every rebuild in dev
    nuxt.hookOnce('build:done', () => logger.info(`${registry.entries.length} toolkit entries`))

    // hook() returns an unsubscribe function — keep it for anything conditional
    const off = nuxt.hook('prepare:types', () => logger.debug('types written'))
    nuxt.hook('close', () => off())
  },
})

Declaring a hook other modules and layers can use:

import type { ToolkitRegistry } from './registry'

export interface ModuleHooks {
  'toolkit:extend': (registry: ToolkitRegistry) => void | Promise<void>
}

declare module '@nuxt/schema' {
  interface NuxtHooks extends ModuleHooks {}
}

// a consuming team layer contributes without writing a module
export default defineNuxtConfig({
  extends: ['@team/nuxt-layer-base'],
  hooks: {
    'toolkit:extend' (registry) {
      registry.add({ name: 'billing', path: '/billing' })
    },
  },
})

The two runtime families, for contrast:

import { defineNitroPlugin } from 'nitropack/runtime'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('render:html', (html, { event }) => {
    html.head.push(`<meta name="x-request-id" content="${event.context.requestId}">`)
  })
})

Exercise

Be able to say