Nuxt•6d ago

Using lifecycle hooks

How do I create a plugin which uses the build:before hook? Adding the hook, I get

Vue: Object literal may only specify known properties, and 'build:before' does not exist in type 'Partial<RuntimeNuxtHooks>'.

The plugin is also not even loaded

14 Replies

kapa.ai•6d ago

Hi @tpluscode. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave: ---------------------- build:before is not a runtime hook, it’s a build/module lifecycle hook. That’s why TypeScript complains when you use it via nuxtApp.hook / RuntimeNuxtHooks – those are only for runtime hooks such as page:finish, page:transition:finish, etc.Runtime hooksLifecycle docs. [Runtime hooks; Nuxt lifecycle] To use build:before you must register it in a module / nuxt.config, not in a runtime plugin. For example in a module:

// modules/my-module.ts
import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module'
  },
  setup(_options, nuxt) {
    nuxt.hook('build:before', () => {
      // your logic here
    })
  }
})

// modules/my-module.ts
import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module'
  },
  setup(_options, nuxt) {
    nuxt.hook('build:before', () => {
      // your logic here
    })
  }
})

Then add the module to nuxt.config.ts so that it’s loaded and the hook runs as part of the build/module lifecycle. [Module hook usage]
If you try to declare build:before in a runtime plugin, it won’t be loaded for that hook and TypeScript will keep flagging it because RuntimeNuxtHooks doesn’t include build:before. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•6d ago

<@555413648382623754> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

tpluscodeOP•6d ago

how do I add a local module? @kapa.ai

kapa.ai•6d ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- To add a local Nuxt module, you register its file path in nuxt.config instead of using a package name. For example, if your local module is at ./modules/my-module.ts, configure it like:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    './modules/my-module', // relative path to your local module
  ],
})

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    './modules/my-module', // relative path to your local module
  ],
})

Nuxt will then load it like any other module. The internal PRs about module path resolution and watching files outside srcDir confirm that local (non‑node_modules) modules are supported and watched correctly during dev builds.[fix kit paths; watch local modules] ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•6d ago

<@555413648382623754> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

tpluscodeOP•6d ago

finally, I would like to configure the module from nuxt.config @kapa.ai

kapa.ai•6d ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- To configure your local module from nuxt.config, you use the module’s configKey (if it defines one) or pass options inline when you register it. A typical module definition:

// modules/my-module.ts
import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule', // ← key used in nuxt.config
  },
  defaults: {
    someOption: true,
  },
  setup(options, nuxt) {
    // `options` is the merged result of defaults + nuxt.config
  }
})

// modules/my-module.ts
import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule', // ← key used in nuxt.config
  },
  defaults: {
    someOption: true,
  },
  setup(options, nuxt) {
    // `options` is the merged result of defaults + nuxt.config
  }
})

Then in nuxt.config.ts you can configure it in either of these ways: 1. Using configKey

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    './modules/my-module',
  ],

  myModule: {
    someOption: false,
    // any other options your module expects
  },
})

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    './modules/my-module',
  ],

  myModule: {
    someOption: false,
    // any other options your module expects
  },
})

Because the module’s meta.configKey is myModule, Nuxt will pass nuxt.options.myModule into the module as options. [Module options via configKey] 2. Inline options in modules array You can also pass options directly when registering:

export default defineNuxtConfig({
  modules: [
    ['./modules/my-module', { someOption: false }],
  ],
})

export default defineNuxtConfig({
  modules: [
    ['./modules/my-module', { someOption: false }],
  ],
})

Again, those options are received as the options argument in your module’s setup function. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•6d ago

<@555413648382623754> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

tpluscodeOP•6d ago

ok, also the config is TS, so I'd like to extend the type to recognise my config key @kapa.ai

kapa.ai•6d ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- To get type‑safe access to your module config key in nuxt.config.ts, you need to augment Nuxt’s types so that your key is part of NuxtConfig / NuxtOptions. With the current Nuxt type setup, the recommended pattern is to put your augmentation in a .d.ts file that Nuxt’s TS project already picks up, and declare it in the correct context. Nuxt’s own docs/PRs describe this as “augmenting types with TS project references” and note that you should not need to touch tsconfig.json manually for it in most cases.[Type augmentation docs] For example (simplified from the pattern used for global types):[Global types example]

// types/my-module.d.ts
import type { NuxtConfig } from 'nuxt/schema'

declare module 'nuxt/schema' {
  interface NuxtConfig {
    myModule?: {
      // your options here
      someOption?: boolean
    }
  }

  interface NuxtOptions {
    myModule?: {
      someOption?: boolean
    }
  }
}

// make this a module
export {}

// types/my-module.d.ts
import type { NuxtConfig } from 'nuxt/schema'

declare module 'nuxt/schema' {
  interface NuxtConfig {
    myModule?: {
      // your options here
      someOption?: boolean
    }
  }

  interface NuxtOptions {
    myModule?: {
      someOption?: boolean
    }
  }
}

// make this a module
export {}

Place this file in a location Nuxt’s app TS context already includes (for example types/), so the augmentation is picked up without extra tsconfig changes.[Type inclusion behavior; Project references note] After that, defineNuxtConfig will recognize:

export default defineNuxtConfig({
  myModule: {
    someOption: false,
  },
})

export default defineNuxtConfig({
  myModule: {
    someOption: false,
  },
})

If your editor still doesn’t see it, ensure: - You’re using the workspace TypeScript version (VS Code setting). [TS plugin note] - The augmentation file is in the app context (not only nodeTsConfig), as mentioned in the project‑references docs. [Project references note] ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•6d ago

<@555413648382623754> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

tpluscodeOP•6d ago

I successfully attached to build:before hook. Unfortunately, builder:watch is not working. why? @kapa.ai

kapa.ai•6d ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- build:before is a Nuxt build/module lifecycle hook, while builder:watch is a more specific hook that only runs when Nuxt’s internal builder starts/stops watching files. In the provided knowledge sources there is only a brief mention that Nuxt recently added watching support for some paths outside srcDir so that local modules can trigger restarts again, but there is no explicit documentation about when or how builder:watch is fired, or how to use it from a module.[watch local modules] Because of that, I can’t say from the sources why your builder:watch hook isn’t firing (whether it’s deprecated, renamed, limited to certain builders, or only triggered under specific conditions). The Nuxt lifecycle docs mentioned in the PR reference also don’t detail this hook’s behavior.[Nuxt lifecycle] So based strictly on the available information: - It’s expected that build:before works in a local module. - There is no clear, documented guarantee (in these sources) that builder:watch is available or works the same way, and no example of its correct use. If you rely on builder:watch, you may need to: - Check the latest Nuxt hooks documentation (outside these sources) to confirm if it’s still a public hook and under which name. - Consider using other documented hooks around build/dev server or file watching instead, if builder:watch is no longer supported. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•6d ago

<@555413648382623754> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

Gaming

Programming

Using lifecycle hooks

Did you find this page helpful?