模块是 Nuxt 的构建块。Kit 提供了一组工具来帮助您创建和使用模块。您可以使用这些工具来创建自己的模块或重用现有模块。例如，您可以使用 defineNuxtModule 函数来定义模块，并使用 installModule 函数以编程方式安装模块。

defineNuxtModule

定义一个 Nuxt 模块，自动将默认值与用户提供的选项合并，安装提供的任何钩子，并调用可选的设置函数以实现完全控制。

用法

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!')
    }
  }
})

类型

// @errors: 2391
import type { ModuleDefinition, ModuleOptions, NuxtModule } from '@nuxt/schema'
// ---cut---
export function defineNuxtModule<TOptions extends ModuleOptions> (
  definition?: ModuleDefinition<TOptions, Partial<TOptions>, false> | NuxtModule<TOptions, Partial<TOptions>, false>,
): NuxtModule<TOptions, TOptions, false>

参数

definition: 模块定义对象或模块函数。模块定义对象应包含以下属性：

示例

使用 configKey 使您的模块可配置

在定义 Nuxt 模块时，您可以设置 configKey 来指定用户应如何在其 nuxt.config 中配置模块。

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!')
    }
  }
})

用户可以在 nuxt.config 中的相应键下为此模块提供选项。

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

定义模块兼容性要求

如果您正在开发一个 Nuxt 模块并使用仅在特定 Nuxt 版本中支持的 API，强烈建议包括 compatibility.nuxt。

export default defineNuxtModule({
  meta: {
    name: '@nuxt/icon',
    configKey: 'icon',
    compatibility: {
      // 以 semver 格式要求的 nuxt 版本。
      nuxt: '>=3.0.0', // 或使用 '^3.0.0'
    },
  },
  async setup() {
    const resolver = createResolver(import.meta.url)
    // 实现
  },
})

如果用户尝试使用与 Nuxt 版本不兼容的模块，他们将在控制台中收到警告。

 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

以编程方式安装指定的 Nuxt 模块。当您的模块依赖于其他模块时，这很有帮助。您可以将模块选项作为对象传递给 inlineOptions，它们将传递给模块的 setup 函数。

用法

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

export default defineNuxtModule({  
  async setup () {
    // 将安装 @nuxtjs/fontaine，使用 Roboto 字体和 Impact 备用字体
    await installModule('@nuxtjs/fontaine', {
      // 模块配置
      fonts: [
        {
          family: 'Roboto',
          fallbacks: ['Impact'],
          fallbackName: 'fallback-a',
        }
      ]
    })
  }
})

类型

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

参数

示例

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

export default defineNuxtModule({  
  async setup (options, nuxt) {
    // 将安装 @nuxtjs/fontaine，使用 Roboto 字体和 Impact 备用字体
    await installModule('@nuxtjs/fontaine', {
      // 模块配置
      fonts: [
        {
          family: 'Roboto',
          fallbacks: ['Impact'],
          fallbackName: 'fallback-a',
        }
      ]
    })
  }
})