v3.17
Nuxt on GitHub

Modules

Source
Nuxt Kit provides a set of utilities to help you create and use modules. You can use these utilities to create your own modules or to reuse existing modules.

Modules are the building blocks of Nuxt. Kit provides a set of utilities to help you create and use modules. You can use these utilities to create your own modules or to reuse existing modules. For example, you can use the defineNuxtModule function to define a module and the installModule function to install a module programmatically.

defineNuxtModule

Define a Nuxt module, automatically merging defaults with user provided options, installing any hooks that are provided, and calling an optional setup function for full control.

Usage

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule'
  },
  defaults: {
    enabled: true
  },
  setup (options) {
    if (options.enabled) {
      console.log('My Nuxt module is enabled!')
    }
  }
})

Type

export function defineNuxtModule<TOptions extends ModuleOptions> (
  definition?: ModuleDefinition<TOptions, Partial<TOptions>, false> | NuxtModule<TOptions, Partial<TOptions>, false>,
): NuxtModule<TOptions, TOptions, false>

Parameters

definition: A module definition object or a module function. The module definition object should contain the following properties:

PropertyTypeRequiredDescription
metaModuleMetafalseMetadata of the module. It defines the module name, version, config key and compatibility.
defaultsT | ((nuxt: Nuxt) => T)falseDefault options for the module. If a function is provided, it will be called with the Nuxt instance as the first argument.
schemaTfalseSchema for the module options. If provided, options will be applied to the schema.
hooksPartial<NuxtHooks>falseHooks to be installed for the module. If provided, the module will install the hooks.
setup(this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable<void | false | ModuleSetupInstallResult>falseSetup function for the module. If provided, the module will call the setup function.

Examples

Using configKey to Make Your Module Configurable

When defining a Nuxt module, you can set a configKey to specify how users should configure the module in their nuxt.config.

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule'
  },
  defaults: {
    // Module options
    enabled: true
  },
  setup (options) {
    if (options.enabled) {
      console.log('My Nuxt module is enabled!')
    }
  }
})

Users can provide options for this module under the corresponding key in nuxt.config.

export default defineNuxtConfig({
  myModule: {
    enabled: false
  }
})

Defining Module Compatibility Requirements

If you're developing a Nuxt module and using APIs that are only supported in specific Nuxt versions, it's highly recommended to include compatibility.nuxt.

export default defineNuxtModule({
  meta: {
    name: '@nuxt/icon',
    configKey: 'icon',
    compatibility: {
      // Required nuxt version in semver format.
      nuxt: '>=3.0.0', // or use '^3.0.0'
    },
  },
  async setup() {
    const resolver = createResolver(import.meta.url)
    // Implement
  },
})

If the user tries to use your module with an incompatible Nuxt version, they will receive a warning in the console.

 WARN  Module @nuxt/icon is disabled due to incompatibility issues:
 - [nuxt] Nuxt version ^3.1.0 is required but currently using 3.0.0

installModule

Install specified Nuxt module programmatically. This is helpful when your module depends on other modules. You can pass the module options as an object to inlineOptions and they will be passed to the module's setup function.

Usage

import { defineNuxtModule, installModule } from '@nuxt/kit'

export default defineNuxtModule({  
  async setup () {
    // will install @nuxtjs/fontaine with Roboto font and Impact fallback
    await installModule('@nuxtjs/fontaine', {
      // module configuration
      fonts: [
        {
          family: 'Roboto',
          fallbacks: ['Impact'],
          fallbackName: 'fallback-a',
        }
      ]
    })
  }
})

Type

async function installModule (moduleToInstall: string | NuxtModule, inlineOptions?: any, nuxt?: Nuxt)

Parameters

PropertyTypeRequiredDescription
moduleToInstallstring | NuxtModuletrueThe module to install. Can be either a string with the module name or a module object itself.
inlineOptionsanyfalseAn object with the module options to be passed to the module's setup function.
nuxtNuxtfalseNuxt instance. If not provided, it will be retrieved from the context via useNuxt() call.

Examples

import { defineNuxtModule, installModule } from '@nuxt/kit'

export default defineNuxtModule({  
  async setup (options, nuxt) {
    // will install @nuxtjs/fontaine with Roboto font and Impact fallback
    await installModule('@nuxtjs/fontaine', {
      // module configuration
      fonts: [
        {
          family: 'Roboto',
          fallbacks: ['Impact'],
          fallbackName: 'fallback-a',
        }
      ]
    })
  }
})