Going Further

Hooks

Hooks for the Nuxt Shopify module

The module provides several hooks that can be used to customize its behavior. These hooks are available in the hooks property of the module configuration and within your Nuxt and Nitro app.

Using client runtime hooks

You can use the client runtime hooks in a Nuxt plugin or Nitro plugin to customize the behavior of any client:

Client-side hooks examples

export default defineNuxtPlugin((app) => {
  app.hooks.hook('storefront:client:configure', ({ config }) => {
    // Modify the config of the client before it is created
    config.logger = logContent => console.log(logContent)
  })

  app.hooks.hook('storefront:client:create', ({ client }) => {
    console.log('Storefront client created:', client)
  })

  app.hooks.hook('storefront:client:request', ({ operation, options }) => {
    console.log('Storefront client request sent:', operation, options)
  })

  app.hooks.hook('storefront:client:response', ({ response, operation, options }) => {
    console.log('Storefront client response received:', response, operation, options)
  })

  app.hooks.hook('storefront:client:errors', ({ errors }) => {
    console.log('Storefront client errors:', errors)
  })
})

export default defineNuxtPlugin((app) => {
  app.hooks.hook('customer-account:client:configure', ({ config }) => {
    // Modify the config of the client before it is created
    config.logger = logContent => console.log(logContent)
  })

  app.hooks.hook('customer-account:client:create', ({ client }) => {
    console.log('Customer account client created:', client)
  })

  app.hooks.hook('customer-account:client:request', ({ operation, options }) => {
    console.log('Customer account client request sent:', operation, options)
  })

  app.hooks.hook('customer-account:client:response', ({ response, operation, options }) => {
    console.log('Customer account client response received:', response, operation, options)
  })

  app.hooks.hook('customer-account:client:errors', ({ errors }) => {
    console.log('Customer account client errors:', errors)
  })
})

Server-side hooks examples

export default defineNitroPlugin((app) => {
  app.hooks.hook('storefront:client:configure', ({ config }) => {
    // Modify the config of the client before it is created
    config.logger = logContent => console.log(logContent)
  })

  app.hooks.hook('storefront:client:create', ({ client }) => {
    console.log('Storefront client created:', client)
  })

  app.hooks.hook('storefront:client:request', ({ operation, options }) => {
    console.log('Storefront client request sent:', operation, options)
  })

  app.hooks.hook('storefront:client:response', ({ response, operation, options }) => {
    console.log('Storefront client response received:', response, operation, options)
  })

  app.hooks.hook('storefront:client:errors', ({ errors }) => {
    console.log('Storefront client errors:', errors)
  })
})

export default defineNitroPlugin((app) => {
  app.hooks.hook('customer-account:client:configure', ({ config }) => {
    // Modify the config of the client before it is created
    config.logger = logContent => console.log(logContent)
  })

  app.hooks.hook('customer-account:client:create', ({ client }) => {
    console.log('Customer account client created:', client)
  })

  app.hooks.hook('customer-account:client:request', ({ operation, options }) => {
    console.log('Customer account client request sent:', operation, options)
  })

  app.hooks.hook('customer-account:client:response', ({ response, operation, options }) => {
    console.log('Customer account client response received:', response, operation, options)
  })

  app.hooks.hook('customer-account:client:errors', ({ errors }) => {
    console.log('Customer account client errors:', errors)
  })
})

export default defineNitroPlugin((app) => {
  app.hooks.hook('admin:client:configure', ({ config }) => {
    // Modify the config of the client before it is created
    config.logger = logContent => console.log(logContent)
  })

  app.hooks.hook('admin:client:create', ({ client }) => {
    console.log('Admin client created:', client)
  })

  app.hooks.hook('admin:client:request', ({ operation, options }) => {
    console.log('Admin client request sent:', operation, options)
  })

  app.hooks.hook('admin:client:response', ({ response, operation, options }) => {
    console.log('Admin client response received:', response, operation, options)
  })

  app.hooks.hook('admin:client:errors', ({ errors }) => {
    console.log('Admin client errors:', errors)
  })
})

The customer account authentication flow runs entirely on the server, so these hooks are only available in a Nitro plugin. Use them to customize the OAuth request, run side effects on login/logout, or observe token refreshes.

~/server/plugins/customer-account-auth.ts

export default defineNitroPlugin((app) => {
  app.hooks.hook('customer-account:auth:authorize', ({ params }) => {
    // Mutate the authorization request, e.g. request a localized login screen
    params.locale = 'en'
  })

  app.hooks.hook('customer-account:auth:success', ({ user, tokens }) => {
    // React to a successful login (merge the guest cart, track analytics, ...)
    console.log('Customer logged in:', user.email)
  })

  app.hooks.hook('customer-account:auth:refresh', ({ tokens }) => {
    console.log('Access token refreshed, expires at:', tokens.expiresAt)
  })

  app.hooks.hook('customer-account:auth:logout', ({ user }) => {
    console.log('Customer logged out:', user?.email)
  })

  app.hooks.hook('customer-account:auth:error', ({ error }) => {
    console.error('Customer account OAuth failed:', error)
  })
})

Admin auth hooks

The admin API authenticates with a machine-to-machine OAuth flow (client credentials, with refresh token rotation), so these hooks are only available in a Nitro plugin. Use them to customize the token request, or to observe when an access token is issued, refreshed, or fails to issue.

These hooks only fire when the module obtains a token on your behalf. They are skipped when a static accessToken is configured.

~/server/plugins/admin-auth.ts

export default defineNitroPlugin((app) => {
  app.hooks.hook('admin:auth:request', ({ params }) => {
    // Mutate the token request body before it is sent
    params.scope = 'my-custom-scope'
  })

  app.hooks.hook('admin:auth:success', ({ token }) => {
    // React to a freshly issued access token (client credentials grant)
    console.log('Admin access token obtained, expires at:', token.expiresAt)
  })

  app.hooks.hook('admin:auth:refresh', ({ token }) => {
    console.log('Admin access token refreshed, expires at:', token.expiresAt)
  })

  app.hooks.hook('admin:auth:error', ({ error }) => {
    console.error('Admin token request failed:', error)
  })
})

Hooks reference

Hooks allows you to hook into the different stages of the module lifecycle.

Nuxt Hooks (Build Time)

Hook	Arguments	Environments	Description
`shopify:config`	`nuxt`, `config`	Server	Called before the parsed module config is persisted into the runtime config
`shopify:setup`	`nuxt`, `config`	Server	Called after the module setup is completed
`storefront:generate:introspection`	`nuxt`, `config`	Server	Called before the storefront introspection schema is generated
`storefront:generate:types`	`nuxt`, `config`	Server	Called before the storefront types are generated
`storefront:generate:operations`	`nuxt`, `config`	Server	Called before the storefront operations are generated
`customer-account:generate:introspection`	`nuxt`, `config`	Server	Called before the customer account introspection schema is generated
`customer-account:generate:types`	`nuxt`, `config`	Server	Called before the customer account types are generated
`customer-account:generate:operations`	`nuxt`, `config`	Server	Called before the customer account operations are generated
`admin:generate:introspection`	`nuxt`, `config`	Server	Called before the admin introspection schema is generated
`admin:generate:types`	`nuxt`, `config`	Server	Called before the admin types are generated
`admin:generate:operations`	`nuxt`, `config`	Server	Called before the admin operations are generated

App Hooks (Runtime)

Hook	Arguments	Environments	Description
`analytics:ready`	`shop`	Client	Called once analytics is ready and the shop analytics are resolved
`analytics:publish`	`event`, `payload`	Client	Called whenever an analytics event is published
`storefront:client:configure`	`config`	Server & Client	Called before the storefront client is created
`storefront:client:create`	`client`	Server & Client	Called after the storefront client is created
`storefront:client:request`	`operation`, `options`	Server & Client	Called before the storefront client sends a request
`storefront:client:response`	`response`, `operation`, `options`	Server & Client	Called after the storefront client receives a response
`storefront:client:errors`	`errors`	Server & Client	Called when a storefront client request contains errors
`customer-account:client:configure`	`config`	Server & Client	Called before the customer account client is created
`customer-account:client:create`	`client`	Server & Client	Called after the customer account client is created
`customer-account:client:request`	`operation`, `options`	Server & Client	Called before the customer account client sends a request
`customer-account:client:response`	`response`, `operation`, `options`	Server & Client	Called after the customer account client receives a response
`customer-account:client:errors`	`errors`	Server & Client	Called when a customer account client request contains errors

Server Hooks (Runtime)

Hook	Arguments	Environments	Description
`storefront:client:configure`	`config`	Server	Called before the storefront client is created
`storefront:client:create`	`client`	Server	Called after the storefront client is created
`storefront:client:request`	`operation`, `options`	Server	Called before the storefront client sends a request
`storefront:client:response`	`response`, `operation`, `options`	Server	Called after the storefront client receives a response
`storefront:client:errors`	`errors`	Server	Called when a storefront client request contains errors
`customer-account:client:configure`	`config`	Server	Called before the customer account client is created
`customer-account:client:create`	`client`	Server	Called after the customer account client is created
`customer-account:client:request`	`operation`, `options`	Server	Called before the customer account client sends a request
`customer-account:client:response`	`response`, `operation`, `options`	Server	Called after the customer account client receives a response
`customer-account:client:errors`	`errors`	Server	Called when a customer account client request contains errors
`customer-account:auth:authorize`	`params`	Server	Called before redirecting to Shopify to start the OAuth flow (mutable `params`)
`customer-account:auth:success`	`user`, `tokens`	Server	Called after a successful login, before the session is persisted
`customer-account:auth:refresh`	`tokens`	Server	Called after the customer account access token is refreshed
`customer-account:auth:logout`	`user`, `idToken`	Server	Called before the session is cleared on logout
`customer-account:auth:error`	`error`	Server	Called when the customer account OAuth flow fails
`admin:auth:request`	`params`	Server	Called before the admin access token request is sent (mutable `params`)
`admin:auth:success`	`token`	Server	Called after an admin access token is obtained (client credentials grant)
`admin:auth:refresh`	`token`	Server	Called after the admin access token is refreshed (refresh token grant)
`admin:auth:error`	`error`	Server	Called when the admin access token request fails
`admin:client:configure`	`config`	Server	Called before the admin client is created
`admin:client:create`	`client`	Server	Called after the admin client is created
`admin:client:request`	`operation`, `options`	Server	Called before the admin client sends a request
`admin:client:response`	`response`, `operation`, `options`	Server	Called after the admin client receives a response
`admin:client:errors`	`errors`	Server	Called when an admin client request contains errors

Edit this pageorReport an issue

Using the Cart

How to use the cart in your Shopify store in Nuxt

GraphiQL Sandbox

Using GraphiQL with Shopify in Nuxt