モジュール

Nuxt Kit は、モジュールの作成と使用を支援する一連のユーティリティを提供します。これらのユーティリティを使用して、独自のモジュールを作成したり、既存のモジュールを再利用したりできます。

モジュールは 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!')
    }
  },
})

タイプ

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>
}

パラメーター

定義: モジュール定義オブジェクトまたはモジュール関数。モジュール定義オブジェクトには、以下のプロパティを含める必要があります。

プロパティ	タイプ	必須	説明
`meta`	`ModuleMeta`	`false`	モジュールのメタデータ。モジュールの名前、バージョン、設定キー、互換性を定義します。
`defaults`	`T \| ((nuxt: Nuxt) => T)`	`false`	モジュールのデフォルトオプション。関数が提供された場合、Nuxt インスタンスが最初の引数として渡されて呼び出されます。
`schema`	`T`	`false`	モジュールオプションのスキーマ。提供された場合、オプションはスキーマに適用されます。
`hooks`	`Partial<NuxtHooks>`	`false`	モジュールにインストールするフック。提供された場合、モジュールはフックをインストールします。
`onInstall`	`(nuxt: Nuxt) => Awaitable<void>`	`false`	モジュールが最初にインストールされたときに呼び出されるライフサイクルフック。`meta.name` と `meta.version` が定義されている必要があります。
`onUpgrade`	`(options: T, nuxt: Nuxt, previousVersion: string) => Awaitable<void>`	`false`	モジュールが新しいバージョンにアップグレードされたときに呼び出されるライフサイクルフック。`meta.name` と `meta.version` が定義されている必要があります。
`setup`	`(this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable<void \| false \| ModuleSetupInstallResult>`	`false`	モジュールのセットアップ関数。提供された場合、モジュールはセットアップ関数を呼び出します。

例

`configKey` を使用してモジュールを設定可能にする

Nuxt モジュールを定義する際、ユーザーが nuxt.config でモジュールを設定する方法を指定するために、configKey を設定できます。

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

ユーザーは、nuxt.config の対応するキーの下でこのモジュールのオプションを提供できます。

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

モジュールの互換性要件の定義

Nuxt モジュールを開発しており、特定の Nuxt バージョンでのみサポートされている API を使用している場合、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'
    },
  },
  setup () {
    const resolver = createResolver(import.meta.url)
    // Implement
  },
})

ユーザーが互換性のない 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'

// Define your module options interface
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 is properly typed as:
    // {
    //   apiKey: string          // Required, no default provided
    //   baseURL: string         // Required, has default value
    //   timeout: number         // Optional, has default value
    //   retries: number         // Optional, has default value
    // }

    console.log(resolvedOptions.baseURL) // ✅ TypeScript knows this is always defined
    console.log(resolvedOptions.timeout) // ✅ TypeScript knows this is always defined
    console.log(resolvedOptions.retries) // ✅ TypeScript knows this is always defined
  },
})

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

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

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

ライフサイクルフックが機能するためには、モジュール定義で meta.name と meta.version の両方を必ず提供する必要があります。フックはこれらの値を使用して、プロジェクトの .nuxtrc ファイルにモジュールのインストール状態を記録します。

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

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

onUpgrade は、モジュールのバージョンが上がるたびに (セマンティックバージョニングの比較を使用して) 実行されますが、各バージョンアップにつき一度だけです。

例

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

export default defineNuxtModule({
  meta: {
    name: 'my-awesome-module',
    version: '1.2.0', // Required for lifecycle hooks
    configKey: 'myAwesomeModule',
  },
  defaults: {
    apiKey: '',
    enabled: true,
  },

  onInstall (nuxt) {
    // This runs only when the module is first installed
    console.log('Setting up my-awesome-module for the first time!')

    // You might want to:
    // - Create initial configuration files
    // - Set up database schemas
    // - Display welcome messages
    // - Perform initial data migration
  },

  onUpgrade (options, nuxt, previousVersion) {
    // This runs when the module is upgraded to a newer version
    console.log(`Upgrading my-awesome-module from ${previousVersion} to 1.2.0`)

    // You might want to:
    // - Migrate configuration files
    // - Update database schemas
    // - Clean up deprecated files
    // - Display upgrade notes

    if (semver.lt(previousVersion, '1.1.0')) {
      console.log('⚠️  Breaking changes in 1.1.0 - please check the migration guide')
    }
  },

  setup (options, nuxt) {
    // Regular setup logic runs on every build
    if (options.enabled) {
      // Configure the module
    }
  },
})

`installModule`

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

使用方法

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',
        },
      ],
    })
  },
})

タイプ

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

パラメーター

プロパティ	タイプ	必須	説明
`moduleToInstall`	`string \| NuxtModule`	`true`	インストールするモジュール。モジュール名の文字列、またはモジュールオブジェクト自体を指定できます。
`inlineOptions`	`any`	`false`	モジュールの `setup` 関数に渡されるモジュールオプションを含むオブジェクト。
`nuxt`	`Nuxt`	`false`	Nuxt インスタンス。提供されていない場合、`useNuxt()` の呼び出しを介してコンテキストから取得されます。

例

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',
        },
      ],
    })
  },
})

お役に立ちましたか？

問題を報告またはGitHub でこのページを編集

nuxt upgrade

upgrade コマンドは Nuxt を最新バージョンにアップグレードします。

ランタイム設定

Nuxt Kit は、Nuxt のランタイム設定にアクセスして変更するのに役立つ一連のユーティリティを提供します。