1---
2name: lifecycle-hooks
3description: Nuxt and Nitro hooks for extending build-time and runtime behavior
4---
5 
6# Lifecycle Hooks
7 
8Nuxt provides hooks to tap into the build process, application lifecycle, and server runtime.
9 
10## Build-time Hooks (Nuxt)
11 
12Used in `nuxt.config.ts` or modules:
13 
14### In nuxt.config.ts
15 
16```ts
17// nuxt.config.ts
18export default defineNuxtConfig({
19  hooks: {
20    'build:before': () => {
21      console.log('Build starting...')
22    },
23    'pages:extend': (pages) => {
24      // Add custom pages
25      pages.push({
26        name: 'custom',
27        path: '/custom',
28        file: '~/pages/custom.vue',
29      })
30    },
31    'components:dirs': (dirs) => {
32      // Add component directories
33      dirs.push({ path: '~/extra-components' })
34    },
35  },
36})
37```
38 
39### In Modules
40 
41```ts
42// modules/my-module.ts
43export default defineNuxtModule({
44  setup(options, nuxt) {
45    nuxt.hook('ready', async (nuxt) => {
46      console.log('Nuxt is ready')
47    })
48 
49    nuxt.hook('close', async (nuxt) => {
50      console.log('Nuxt is closing')
51    })
52 
53    nuxt.hook('modules:done', () => {
54      console.log('All modules loaded')
55    })
56  },
57})
58```
59 
60### Common Build Hooks
61 
62| Hook | When |
63|------|------|
64| `ready` | Nuxt initialization complete |
65| `close` | Nuxt is closing |
66| `modules:done` | All modules installed |
67| `build:before` | Before build starts |
68| `build:done` | Build complete |
69| `pages:extend` | Pages routes resolved |
70| `components:dirs` | Component dirs being resolved |
71| `imports:extend` | Auto-imports being resolved |
72| `nitro:config` | Before Nitro config finalized |
73| `vite:extend` | Vite context created |
74| `vite:extendConfig` | Before Vite config finalized |
75 
76## App Hooks (Runtime)
77 
78Used in plugins and composables:
79 
80### In Plugins
81 
82```ts
83// plugins/lifecycle.ts
84export default defineNuxtPlugin((nuxtApp) => {
85  nuxtApp.hook('app:created', (vueApp) => {
86    console.log('Vue app created')
87  })
88 
89  nuxtApp.hook('app:mounted', (vueApp) => {
90    console.log('App mounted')
91  })
92 
93  nuxtApp.hook('page:start', () => {
94    console.log('Page navigation starting')
95  })
96 
97  nuxtApp.hook('page:finish', () => {
98    console.log('Page navigation finished')
99  })
100 
101  nuxtApp.hook('page:loading:start', () => {
102    console.log('Page loading started')
103  })
104 
105  nuxtApp.hook('page:loading:end', () => {
106    console.log('Page loading ended')
107  })
108})
109```
110 
111### Common App Hooks
112 
113| Hook | When |
114|------|------|
115| `app:created` | Vue app created |
116| `app:mounted` | Vue app mounted (client only) |
117| `app:error` | Fatal error occurred |
118| `page:start` | Page navigation starting |
119| `page:finish` | Page navigation finished |
120| `page:loading:start` | Loading indicator should show |
121| `page:loading:end` | Loading indicator should hide |
122| `link:prefetch` | Link is being prefetched |
123 
124### Using Runtime Hooks
125 
126```ts
127// composables/usePageTracking.ts
128export function usePageTracking() {
129  const nuxtApp = useNuxtApp()
130 
131  nuxtApp.hook('page:finish', () => {
132    trackPageView(useRoute().path)
133  })
134}
135```
136 
137## Server Hooks (Nitro)
138 
139Used in server plugins:
140 
141```ts
142// server/plugins/hooks.ts
143export default defineNitroPlugin((nitroApp) => {
144  // Modify HTML before sending
145  nitroApp.hooks.hook('render:html', (html, { event }) => {
146    html.head.push('<meta name="custom" content="value">')
147    html.bodyAppend.push('<script>console.log("injected")</script>')
148  })
149 
150  // Modify response
151  nitroApp.hooks.hook('render:response', (response, { event }) => {
152    console.log('Sending response:', response.statusCode)
153  })
154 
155  // Before request
156  nitroApp.hooks.hook('request', (event) => {
157    console.log('Request:', event.path)
158  })
159 
160  // After response
161  nitroApp.hooks.hook('afterResponse', (event) => {
162    console.log('Response sent')
163  })
164})
165```
166 
167### Common Nitro Hooks
168 
169| Hook | When |
170|------|------|
171| `request` | Request received |
172| `beforeResponse` | Before sending response |
173| `afterResponse` | After response sent |
174| `render:html` | Before HTML is sent |
175| `render:response` | Before response is finalized |
176| `error` | Error occurred |
177 
178## Custom Hooks
179 
180### Define Custom Hook Types
181 
182```ts
183// types/hooks.d.ts
184import type { HookResult } from '@nuxt/schema'
185 
186declare module '#app' {
187  interface RuntimeNuxtHooks {
188    'my-app:event': (data: MyEventData) => HookResult
189  }
190}
191 
192declare module '@nuxt/schema' {
193  interface NuxtHooks {
194    'my-module:init': () => HookResult
195  }
196}
197 
198declare module 'nitropack/types' {
199  interface NitroRuntimeHooks {
200    'my-server:event': (data: any) => void
201  }
202}
203```
204 
205### Call Custom Hooks
206 
207```ts
208// In a plugin
209export default defineNuxtPlugin((nuxtApp) => {
210  // Call custom hook
211  nuxtApp.callHook('my-app:event', { type: 'custom' })
212})
213 
214// In a module
215export default defineNuxtModule({
216  setup(options, nuxt) {
217    nuxt.callHook('my-module:init')
218  },
219})
220```
221 
222## useRuntimeHook
223 
224Call hooks at runtime from components:
225 
226```vue
227<script setup lang="ts">
228// Register a callback for a runtime hook
229useRuntimeHook('app:error', (error) => {
230  console.error('App error:', error)
231})
232</script>
233```
234 
235## Hook Examples
236 
237### Page View Tracking
238 
239```ts
240// plugins/analytics.client.ts
241export default defineNuxtPlugin((nuxtApp) => {
242  nuxtApp.hook('page:finish', () => {
243    const route = useRoute()
244    analytics.track('pageview', {
245      path: route.path,
246      title: document.title,
247    })
248  })
249})
250```
251 
252### Performance Monitoring
253 
254```ts
255// plugins/performance.client.ts
256export default defineNuxtPlugin((nuxtApp) => {
257  let navigationStart: number
258 
259  nuxtApp.hook('page:start', () => {
260    navigationStart = performance.now()
261  })
262 
263  nuxtApp.hook('page:finish', () => {
264    const duration = performance.now() - navigationStart
265    console.log(`Navigation took ${duration}ms`)
266  })
267})
268```
269 
270### Inject HTML
271 
272```ts
273// server/plugins/inject.ts
274export default defineNitroPlugin((nitroApp) => {
275  nitroApp.hooks.hook('render:html', (html) => {
276    html.head.push(`
277      <script>
278        window.APP_CONFIG = ${JSON.stringify(config)}
279      </script>
280    `)
281  })
282})
283```
284 
285<!-- 
286Source references:
287- https://nuxt.com/docs/guide/going-further/hooks
288- https://nuxt.com/docs/api/advanced/hooks
289-->
290