モジュールは 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>

export function defineNuxtModule<TOptions extends ModuleOptions> (): {
  with: <TOptionsDefaults extends Partial<TOptions>> (
    definition: ModuleDefinition<TOptions, TOptionsDefaults, true> | NuxtModule<TOptions, TOptionsDefaults, true>
  ) => NuxtModule<TOptions, TOptionsDefaults, true>
}

パラメータ

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 バージョンでのみサポートされる API を使用して Nuxt モジュールを開発している場合は、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

.with() を使用した解決済みオプションの型安全性

解決済み/マージ済みのモジュールオプションに型安全性が必要な場合は、.with() メソッドを使用できます。これにより、TypeScript はモジュールのデフォルトとセットアップ関数が受け取る最終的な解決済みオプションとの関係を適切に推論できます。

import { defineNuxtModule } from '@nuxt/kit'

// モジュールオプションインターフェースを定義
interface ModuleOptions {
  apiKey: string
  baseURL: string
  timeout?: number
  retries?: number
}

export default defineNuxtModule<ModuleOptions>().with({
  meta: {
    name: '@nuxtjs/my-api',
    configKey: 'myApi'
  },
  defaults: {
    baseURL: 'https://api.example.com',
    timeout: 5000,
    retries: 3
  },
  setup(resolvedOptions, nuxt) {
    // resolvedOptions は適切に型付けされています：
    // {
    //   apiKey: string          // 必須、デフォルトは提供されていない
    //   baseURL: string         // 必須、デフォルト値あり
    //   timeout: number         // オプション、デフォルト値あり
    //   retries: number         // オプション、デフォルト値あり  
    // }
    
    console.log(resolvedOptions.baseURL) // ✅ TypeScript はこれが常に定義されていることを知っています
    console.log(resolvedOptions.timeout) // ✅ TypeScript はこれが常に定義されていることを知っています
    console.log(resolvedOptions.retries) // ✅ TypeScript はこれが常に定義されていることを知っています
  }
})

.with() を使用しない場合、resolvedOptions パラメータは生の ModuleOptions インターフェースとして型付けされ、timeout と retries はデフォルトが提供されていても undefined になる可能性があります。.with() メソッドは、デフォルト値がそれらのプロパティを解決済みオプションで非オプションにすることを TypeScript に理解させます。

モジュールのインストールとアップグレードのためのライフサイクルフックの使用

モジュールが最初にインストールされたときや新しいバージョンにアップグレードされたときに実行されるライフサイクルフックを定義できます。これらのフックは、一度限りのセットアップタスク、データベースの移行、またはクリーンアップ操作を実行するのに役立ちます。

ライフサイクルフックはメインの setup 関数の前に実行され、フックがエラーをスローした場合、それはログに記録されますが、ビルドプロセスを停止しません。

onInstall は、モジュールがプロジェクトに最初に追加されたときにのみ実行されます。

onUpgrade は、モジュールのバージョンが増加するたびに（semver 比較を使用して）実行されますが、各バージョンアップごとに一度だけです。

例

import { defineNuxtModule } from '@nuxt/kit'
import semver from 'semver'

export default defineNuxtModule({
  meta: {
    name: 'my-awesome-module',
    version: '1.2.0', // ライフサイクルフックに必要
    configKey: 'myAwesomeModule'
  },
  defaults: {
    apiKey: '',
    enabled: true
  },
  
  onInstall(nuxt) {
    // これはモジュールが最初にインストールされたときにのみ実行されます
    console.log('Setting up my-awesome-module for the first time!')
    
    // 次のことを行うかもしれません：
    // - 初期設定ファイルの作成
    // - データベーススキーマの設定
    // - ウェルカムメッセージの表示
    // - 初期データ移行の実行
  },
  
  onUpgrade(options, nuxt, previousVersion) {
    // これはモジュールが新しいバージョンにアップグレードされたときに実行されます
    console.log(`Upgrading my-awesome-module from ${previousVersion} to 1.2.0`)
    
    // 次のことを行うかもしれません：
    // - 設定ファイルの移行
    // - データベーススキーマの更新  
    // - 廃止されたファイルのクリーンアップ
    // - アップグレードノートの表示
    
    if (semver.lt(previousVersion, '1.1.0')) {
      console.log('⚠️  Breaking changes in 1.1.0 - please check the migration guide')
    }
  },
  
  setup(options, nuxt) {
    // 通常のセットアップロジックは毎回のビルドで実行されます
    if (options.enabled) {
      // モジュールを設定
    }
  }
})

installModule

指定された Nuxt モジュールをプログラム的にインストールします。これは、モジュールが他のモジュールに依存している場合に役立ちます。モジュールオプションをオブジェクトとして inlineOptions に渡すことができ、それらはモジュールの setup 関数に渡されます。

使用法

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

export default defineNuxtModule({  
  async setup () {
    // Roboto フォントと Impact フォールバックで @nuxtjs/fontaine をインストールします
    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) {
    // Roboto フォントと Impact フォールバックで @nuxtjs/fontaine をインストールします
    await installModule('@nuxtjs/fontaine', {
      // モジュール設定
      fonts: [
        {
          family: 'Roboto',
          fallbacks: ['Impact'],
          fallbackName: 'fallback-a',
        }
      ]
    })
  }
})