/nuxt

Lifecycle Hooks

Nuxt provides hooks to tap into the build process, application lifecycle, and server runtime.

Build-time Hooks (Nuxt)

Used in nuxt.config.ts or modules:

In nuxt.config.ts

// nuxt.config.ts
export default defineNuxtConfig({
  hooks: {
    'build:before': () => {
      console.log('Build starting...')
    },
    'pages:extend': (pages) => {
      // Add custom pages
      pages.push({
        name: 'custom',
        path: '/custom',
        file: '~/pages/custom.vue',
      })
    },
    'components:dirs': (dirs) => {
      // Add component directories
      dirs.push({ path: '~/extra-components' })
    },
  },
})

In Modules

// modules/my-module.ts
export default defineNuxtModule({
  setup(options, nuxt) {
    nuxt.hook('ready', async (nuxt) => {
      console.log('Nuxt is ready')
    })

    nuxt.hook('close', async (nuxt) => {
      console.log('Nuxt is closing')
    })

    nuxt.hook('modules:done', () => {
      console.log('All modules loaded')
    })
  },
})

Common Build Hooks

App Hooks (Runtime)

Used in plugins and composables:

In Plugins

// plugins/lifecycle.ts
export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.hook('app:created', (vueApp) => {
    console.log('Vue app created')
  })

  nuxtApp.hook('app:mounted', (vueApp) => {
    console.log('App mounted')
  })

  nuxtApp.hook('page:start', () => {
    console.log('Page navigation starting')
  })

  nuxtApp.hook('page:finish', () => {
    console.log('Page navigation finished')
  })

  nuxtApp.hook('page:loading:start', () => {
    console.log('Page loading started')
  })

  nuxtApp.hook('page:loading:end', () => {
    console.log('Page loading ended')
  })
})

Common App Hooks

Using Runtime Hooks

// composables/usePageTracking.ts
export function usePageTracking() {
  const nuxtApp = useNuxtApp()

  nuxtApp.hook('page:finish', () => {
    trackPageView(useRoute().path)
  })
}

Server Hooks (Nitro)

Used in server plugins:

In Nitro v3 the plugin factory is definePlugin from nitro:

// server/plugins/hooks.ts
import { definePlugin } from 'nitro'

export default definePlugin((nitroApp) => {
  // Modify HTML before sending
  nitroApp.hooks.hook('render:html', (html, { event }) => {
    html.head.push('<meta name="custom" content="value">')
    html.bodyAppend.push('<script>console.log("injected")</script>')
  })

  // Before request
  nitroApp.hooks.hook('request', (event) => {
    console.log('Request:', event.url.pathname)
  })

  // Single response hook (replaces beforeResponse/afterResponse in v3)
  nitroApp.hooks.hook('response', (response, { event }) => {
    console.log('Sending response')
  })
})

Common Nitro Hooks

Nitro v3: beforeResponse/afterResponse are merged into response. The compatibility layer re-emits them from response when active.

Custom Hooks

Define Custom Hook Types

// types/hooks.d.ts
import type { HookResult } from '@nuxt/schema'

declare module '#app' {
  interface RuntimeNuxtHooks {
    'my-app:event': (data: MyEventData) => HookResult
  }
}

declare module '@nuxt/schema' {
  interface NuxtHooks {
    'my-module:init': () => HookResult
  }
}

declare module 'nitro/types' {
  interface NitroRuntimeHooks {
    'my-server:event': (data: any) => void
  }
}

Nitro v3: nitropack is renamed to nitro — augment nitro/types (not nitropack/types).

Call Custom Hooks

// In a plugin
export default defineNuxtPlugin((nuxtApp) => {
  // Call custom hook
  nuxtApp.callHook('my-app:event', { type: 'custom' })
})

// In a module
export default defineNuxtModule({
  setup(options, nuxt) {
    nuxt.callHook('my-module:init')
  },
})

Nuxt 5: callHook may now return void (not always a Promise), for performance. Always await it instead of chaining .then()/.catch(). Restore the always-Promise behavior with experimental.asyncCallHook: true.

useRuntimeHook

Call hooks at runtime from components:

<script setup lang="ts">
// Register a callback for a runtime hook
useRuntimeHook('app:error', (error) => {
  console.error('App error:', error)
})
</script>

Hook Examples

Page View Tracking

// plugins/analytics.client.ts
export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.hook('page:finish', () => {
    const route = useRoute()
    analytics.track('pageview', {
      path: route.path,
      title: document.title,
    })
  })
})

Performance Monitoring

// plugins/performance.client.ts
export default defineNuxtPlugin((nuxtApp) => {
  let navigationStart: number

  nuxtApp.hook('page:start', () => {
    navigationStart = performance.now()
  })

  nuxtApp.hook('page:finish', () => {
    const duration = performance.now() - navigationStart
    console.log(`Navigation took ${duration}ms`)
  })
})

Inject HTML

// server/plugins/inject.ts
import { definePlugin } from 'nitro'

export default definePlugin((nitroApp) => {
  nitroApp.hooks.hook('render:html', (html) => {
    html.head.push(`
      <script>
        window.APP_CONFIG = ${JSON.stringify(config)}
      </script>
    `)
  })
})