Hooks

Nuxt API Party lets you customize module behavior at various stages. The hook system supports both Nuxt and Nitro environments with fully typed, merged hooks that ensure both generic and endpoint-specific handlers execute in the correct order.

For more information on how to work with hooks, see the Nuxt documentation.

Available Hooks

Hook Name	Arguments	Description
api-party:extend	options	Called during module initialization after options are resolved. Allows modifying endpoint configuration.
api-party:request	ctx, [event]	Called before each API request. This generic hook runs on both Nuxt and Nitro platforms.
api-party:request:${endpointId}	ctx, [event]	Called specifically for the designated endpoint. Merged with the generic request hook.
api-party:response	ctx, [event]	Called after each API response. This generic hook is used to handle response modifications on both platforms.
api-party:response:${endpointId}	ctx, [event]	Called for the specific endpoint response. Merged with the generic response hook.

Merging Hooks

Both generic and endpoint-specific hooks are merged and executed in sequence.

• For requests: The generic api-party:request hook executes first, followed by api-party:request:${endpointId}.
• For responses: The endpoint-specific api-party:response:${endpointId} hook executes first, followed by api-party:response.

Nuxt Runtime Hooks

Register Nuxt runtime hooks in your nuxt.config.ts file, in a client plugin, or at runtime. Use these hooks for extending API endpoints with additional configuration or for intercepting API calls for logging, metrics, or dynamically adding headers.

The only hook called at module initialization is api-party:extend, useful for modifying endpoint configuration before the module is fully initialized. For example, log the resolved server endpoints:

export default defineNuxtConfig({
  modules: ['nuxt-api-party'],

  hooks: {
    'api-party:extend': async (options) => {
      console.log(`Resolved server endpoints:`, options.endpoints)
    },
  },
})

All other hooks are called at runtime, either client-side (or server-side on SSR requests). For example, add headers to all requests using the api-party:request hook:

export default defineNuxtPlugin((nuxtApp) => {
  // Generic hook: executes on every API request
  nuxtApp.hook('api-party:request', (ctx) => {
    // Add a unique request ID to each request
    ctx.options.headers.set('X-Request-Id', Math.random().toString(36).substring(7))
  })
})

Client-Side Execution

All of the Nuxt hooks are executed on the client side by default. Do not use them for sensitive operations like authentication or authorization. Instead, use Nitro hooks for server-side processing.

Nitro Runtime Hooks

For server-side processing, register these hooks in a server plugin. Use them for tasks like dynamically fetching tokens or logging responses.

The most common use case for Nitro hooks is attaching a token to a request before it's sent. For example, attach a user token to a specific endpoint request:

export default defineNitroPlugin((nitroApp) => {
  // Generic request hook: runs before any API request on the server
  nitroApp.hooks.hook('api-party:request', async (ctx, event) => {
    // Do something before each request
  })

  // Endpoint-specific request hook for `myapi`
  nitroApp.hooks.hook('api-party:request:myapi', async (ctx, event) => {
    // Fetch a user token and attach it to the request
    const token = await getUserToken(event)
    ctx.options.headers.set('Authorization', `Bearer ${token}`)
  })

  // Example of a response hook to modify or log responses
  nitroApp.hooks.hook('api-party:response:myapi', async (ctx, event) => {
    // Custom response handling
  })
})