モジュール作成者ガイド

アプリケーションを統合、強化、拡張するためのNuxtモジュールを作成する方法を学びます。

Nuxtの設定およびフックにより、Nuxt のあらゆる側面をカスタマイズし、必要な統合 (Vueプラグイン、CMS、サーバー ルート、コンポーネント、ロギングなど) を追加することができます。

Nuxt モジュールは、nuxi devを使用して開発モードで Nuxt を起動するとき、またはnuxi build で本番用のプロジェクトをビルドするときに順次実行される関数です。 モジュールを使用すると、プロジェクトに不要なボイラープレート(あまり変化することがない、複数の場所で繰り返される定型コードのセクションのこと)を追加したり、Nuxt自体に変更を加えたりすることなく、カスタム ソリューションをカプセル化し、適切にテストし、npmパッケージとして共有できます。

クイックスタート

スターターテンプレートを使用してNuxtモジュールの使用を開始することをお勧めします。

npx nuxi init -t module my-module

これにより、モジュールの開発と公開に必要なすべてのボイラープレートを含むmy-moduleプロジェクトが作成されます。

次のステップ:

• 選択した IDE でmy-moduleを開きます。
• お気に入りのパッケージ マネージャーを使用して依存関係をインストールする。
• npm run dev:prepareを使用して開発用のローカル ファイルを準備する。
• Nuxt モジュールの詳細については、このドキュメントに従ってください。

スターターの使用方法

モジュール スターターを使用して基本的なタスクを実行する方法を学びます。

開発方法

モジュールのソース コードはsrcディレクトリ内に存在しますが、ほとんどの場合、モジュールを開発するには、 Nuxt アプリケーション。 それがplaygroundディレクトリの目的です。 これは、モジュールで実行するようにすでに設定されている、いじることができる Nuxt アプリケーションです。

他の Nuxt アプリケーションと同様に、プレイグラウンドを操作できます。

• npm run devを使用して開発サーバーを起動します。src ディレクトリ内のモジュールに変更を加えると、開発サーバー自体がリロードされます。
• npm run dev:buildでビルドします。

テスト方法

モジュール スターターには、基本的なテスト スイートが付属しています。

• ESLint : npm run lintで実行します。
• Vitest : npm run testまたはnpm run test:watchで実行します。

構築方法

Nuxt モジュールには、@nuxt/module-builderによって提供される独自のビルダーが付属しています。 このビルダーには何も必要ありませんTypeScriptをサポートし、他のNuxtアプリケーションに配布できるようにアセットが適切にバンドルされていることを確認します。

npm run prepackを実行してモジュールをビルドできます。

公開の方法

バージョンを上げてnpm publishコマンドを使用することでモジュールを公開できますが、モジュール スターター リリース スクリプトが付属しており、モジュールの動作バージョンを npm などに確実に公開するのに役立ちます。

リリース スクリプトを使用するには、まずすべての変更をコミットします (Conventional Commitsに従って、バージョンのバンプと変更ログの自動更新も利用することをお勧めします。)、npm run releaseでリリース スクリプトを実行します。

リリース スクリプトを実行すると、次のことが起こります:

まず、次の方法でテスト スイートを実行します:

• リンターの実行 (npm run lint)
• 単体テスト、統合テスト、および e2e テストの実行 (npm run test)
• モジュールのビルド (npm run prepack)

その後、テスト スイートがうまくいった場合は、モジュールの公開が続行されます。

• 従来のコミットに従ってモジュールのバージョンを上げ、変更ログを生成する
• モジュールを npm に公開します (そのために、モジュールは再度ビルドされ、更新されたバージョン番号が公開されたアーティファクトで確実に考慮されます)
• 新しく公開されたバージョンを表すgitタグをgitリモートのoriginにプッシュする

モジュールの開発

Nuxt モジュールには、さまざまな強力な API とパターンが付属しており、可能な限りあらゆる方法で Nuxt アプリケーションを変更できます。 このセクションでは、それらを活用する方法を説明します。

モジュールの構造

2 種類の Nuxt モジュールが考えられます:

• 公開されたモジュールは npm で配布されます。Nuxt Web サイトでいくつかのコミュニティ モジュールのリストを確認できます。
• 「ローカル」モジュール。それらは Nuxt プロジェクト自体内に存在し、 Nuxtの設定にインライン化されるか、modulesディレクトリの一部として存在します。

どちらの場合でも、それらの解剖学的構造は似ています。

モジュール定義

モジュール定義は、モジュールのエントリ ポイントです。 これは、モジュールが Nuxt 設定内で参照されるときに Nuxt によってロードされるものです。

低レベルでは、Nuxtモジュールの定義は、インラインのユーザーオプションとnuxtオブジェクトを受け取る、シンプルで潜在的に非同期な関数です。この関数はNuxtと対話するために使用されます。

export default function (inlineOptions, nuxt) {
  // ここでは好きなことを何でもできます..
  console.log(inlineOptions.token); // `123`
  console.log(nuxt.options.dev); // `true` or `false`
  nuxt.hook("ready", async (nuxt) => {
    console.log("Nuxt is ready");
  });
}

import { defineNuxtModule } from "@nuxt/kit";

export default defineNuxtModule((options, nuxt) => {
  nuxt.hook("pages:extend", (pages) => {
    console.log(`Discovered ${pages.length} pages`);
  });
});

import { defineNuxtModule } from "@nuxt/kit";

export default defineNuxtModule({
  meta: {
    // 通常はモジュールのnpmパッケージ名
    name: "@nuxtjs/example",
    // モジュールオプションを保持する「nuxt.config」内のキー
    configKey: "sample",
    // 互換性の制約
    compatibility: {
      // サポートされているnuxtバージョンのSemverバージョン
      nuxt: "^3.0.0",
    },
  },
  // モジュールのデフォルト構成オプションは、それらを返す関数にすることもできます。
  defaults: {},
  // Nuxt フックを登録するための短縮形コード
  hooks: {},
  // モジュールロジックを保持する関数。非同期にすることができます。
  setup(moduleOptions, nuxt) {
    // ...
  },
});

最終的に、defineNuxtModule は、より低レベルの（inlineOptions、nuxt）モジュールシグネチャを持つラッパー関数を返します。このラッパー関数は、デフォルト値やその他の必要なステップを適用してから、setup関数を呼び出します。

• モジュールオプションを自動的にマージするためのdefaultsとmeta.configKeyをサポート
• 型ヒントと自動型推論
• 基本的な Nuxt 2 互換性のためにシムを追加する
• meta.name または meta.configKey から計算された一意のキーを使用してモジュールが 1 回だけインストールされるようにする
• Nuxt フックを自動的に登録する
• モジュールメタに基づいて互換性の問題を自動的にチェックします
• Nuxt の内部使用のために getOptions と getMeta を公開する
• モジュールが最新のdefineNuxtModuleを使用している限り、下位互換性と上位互換性を確保します。@nuxt/kitのバージョン
• モジュールビルダーツールとの統合

ランタイム ディレクトリ

モジュールは、Nuxt 構成内のすべてのものと同様、アプリケーション ランタイムには含まれません。 ただし、モジュールがインストールされているアプリケーションにランタイムコードを提供したり、モジュールを挿入したりすることが必要になる場合があります。 それが、ランタイム ディレクトリによって可能になります。

ランタイム ディレクトリ内では、Nuxt アプリに関連するあらゆる種類のアセットを提供できます:

• Vue components
• Composables
• Nuxt plugins

サーバーエンジン Nitroに対して:

• API routes
• Middlewares
• Nitro plugins

または、ユーザーの Nuxt アプリケーションに挿入したいその他の種類のアセット:

• Stylesheets
• 3D models
• Images
• etc.

その後、モジュール定義からアプリケーション内にこれらすべてのアセットを挿入できるようになります。

ツール

モジュールには、開発に役立つ一連のファーストパーティ ツールが付属しています。

Info 詳細は、API > Advanced > Kit. を参照してください。

レシピ

モジュールの作成に使用される一般的なレシピはこちらでお探しください。

Nuxt 構成の変更

Nuxt 設定はモジュールによって読み取ったり、変更したりできます。以下は、実験的な機能を有効にするモジュールの例です。

import { defineNuxtModule } from "@nuxt/kit";

export default defineNuxtModule({
  setup(options, nuxt) {
    // experimental オブジェクトが存在しない場合、作成します。
    nuxt.options.experimental ||= {};
    nuxt.options.experimental.componentIslands = true;
  },
});

より複雑な構成変更を処理する必要がある場合は、 defuの使用を検討してください。

ランタイムへのオプションの公開

モジュールはアプリケーション ランタイムの一部ではないため、そのオプションも同様ではありません。 ただし、多くの場合、ランタイムコード内でこれらのモジュールオプションの一部にアクセスする必要がある場合があります。NuxtのruntimeConfigを使用して必要な構成を公開することをお勧めします。

import { defineNuxtModule } from "@nuxt/kit";
import { defu } from "defu";

export default defineNuxtModule({
  setup(options, nuxt) {
    nuxt.options.runtimeConfig.public.myModule = defu(nuxt.options.runtimeConfig.public.myModule, {
      foo: options.foo,
    });
  },
});

const options = useRuntimeConfig().public.myModule;

Info 詳細は、Guide > Going Further > Runtime Config を参照ください。

addPlugin を使用したプラグインの挿入

プラグインは、モジュールにランタイム ロジックを追加する一般的な方法です。 addPluginユーティリティを使用して、モジュールからそれらを登録できます。

import { defineNuxtModule, addPlugin, createResolver } from "@nuxt/kit";

export default defineNuxtModule({
  setup(options, nuxt) {
    // 相対パスを解決するリゾルバを作成します
    const { resolve } = createResolver(import.meta.url);

    addPlugin(resolve("./runtime/plugin"));
  },
});

Info 詳細は、API > Advanced > Kit. を参照してください。

addComponent による Vueコンポーネントの挿入

モジュールがVueコンポーネントを提供する必要がある場合は、addComponentユーティリティを使用して、それらを Nuxtが解決する自動インポートとして追加できます。

import { defineNuxtModule, addComponent } from "@nuxt/kit";

export default defineNuxtModule({
  setup(options, nuxt) {
    const resolver = createResolver(import.meta.url);

    // From the runtime directory
    addComponent({
      name: "MySuperComponent", // name of the component to be used in vue templates
      export: "MySuperComponent", // (optional) if the component is a named (rather than default) export
      filePath: resolver.resolve("runtime/components/MySuperComponent.vue"),
    });

    // From a library
    addComponent({
      name: "MyAwesomeComponent", // name of the component to be used in vue templates
      export: "MyAwesomeComponent", // (optional) if the component is a named (rather than default) export
      filePath: "@vue/awesome-components",
    });
  },
});

addImports および addImportsDir を使用したコンポーザブルの挿入

モジュールがコンポーザブルを提供する必要がある場合は、addImportsユーティリティを使用して、それらを Nuxt の自動インポートとして追加して解決できます。

import { defineNuxtModule, addImports, createResolver } from "@nuxt/kit";

export default defineNuxtModule({
  setup(options, nuxt) {
    const resolver = createResolver(import.meta.url);

    addImports({
      name: "useComposable", // name of the composable to be used
      as: "useComposable",
      from: resolver.resolve("runtime/composables/useComposable"), // path of composable
    });
  },
});

import { defineNuxtModule, addImportsDir, createResolver } from "@nuxt/kit";

export default defineNuxtModule({
  setup(options, nuxt) {
    const resolver = createResolver(import.meta.url);

    addImportsDir(resolver.resolve("runtime/composables"));
  },
});

addServerHandler を使用したサーバールートの挿入

import { defineNuxtModule, addServerHandler, createResolver } from "@nuxt/kit";

export default defineNuxtModule({
  setup(options, nuxt) {
    const resolver = createResolver(import.meta.url);

    addServerHandler({
      route: "/api/hello",
      handler: resolver.resolve("./runtime/server/api/hello/index.get.ts"),
    });
  },
});

import { defineNuxtModule, addServerHandler, createResolver } from "@nuxt/kit";

export default defineNuxtModule({
  setup(options, nuxt) {
    const resolver = createResolver(import.meta.url);

    addServerHandler({
      route: "/api/hello/:name",
      handler: resolver.resolve("./runtime/server/api/hello/[name].get.ts"),
    });
  },
});

他のアセットの挿入

モジュールが他の種類のアセットを提供する必要がある場合は、それらを注入することもできます。 これは、Nuxt のcss 配列を通じてスタイルシートを挿入する簡単なモジュールの例です。

import { defineNuxtModule, addPlugin, createResolver } from "@nuxt/kit";

export default defineNuxtModule({
  setup(options, nuxt) {
    const { resolve } = createResolver(import.meta.url);

    nuxt.options.css.push(resolve("./runtime/style.css"));
  },
});

import { defineNuxtModule, createResolver } from "@nuxt/kit";

export default defineNuxtModule({
  setup(options, nuxt) {
    const { resolve } = createResolver(import.meta.url);

    nuxt.hook("nitro:config", async (nitroConfig) => {
      nitroConfig.publicAssets ||= [];
      nitroConfig.publicAssets.push({
        dir: resolve("./runtime/public"),
        maxAge: 60 * 60 * 24 * 365, // 1 year
      });
    });
  },
});

モジュール内で他のモジュールを使用する

モジュールが他のモジュールに依存している場合は、Nuxt Kit のinstallModule ユーティリティを使用してモジュールを追加できます。たとえば、モジュールで Nuxt Tailwindを使用したい場合は、以下のように追加できます。

import { defineNuxtModule, createResolver, installModule } from "@nuxt/kit";

export default defineNuxtModule<ModuleOptions>({
  async setup(options, nuxt) {
    const { resolve } = createResolver(import.meta.url);

    // Tailwind を含む CSS ファイルを挿入できます
    nuxt.options.css.push(resolve("./runtime/assets/styles.css"));

    await installModule("@nuxtjs/tailwindcss", {
      // モジュール設定
      exposeConfig: true,
      config: {
        darkMode: "class",
        content: {
          files: [resolve("./runtime/components/**/*.{vue,mjs,ts}"), resolve("./runtime/*.{mjs,js,ts}")],
        },
      },
    });
  },
});

フックの使用

ライフサイクルフックを使用すると、Nuxt のほぼすべての側面を拡張できます。 モジュールはプログラム的に、または定義内のhooksを通じてモジュールにフックできます。

import { defineNuxtModule, addPlugin, createResolver } from "@nuxt/kit";

export default defineNuxtModule({
  // `hooks` を介して `app:error` にフックします。
  hooks: {
    "app:error": (err) => {
      console.info(`This error happened: ${err}`);
    },
  },
  setup(options, nuxt) {
    // `pages:extend`にフックする
    nuxt.hook("pages:extend", (pages) => {
      console.info(`Discovered ${pages.length} pages`);
    });
  },
});

import { defineNuxtModule } from "@nuxt/kit";
export default defineNuxtModule({
  setup(options, nuxt) {
    nuxt.hook("close", async (nuxt) => {
      // カスタムコードを記述
    });
  },
});

テンプレート / 仮想ファイルの追加

ユーザーのアプリにインポートできる仮想ファイルを追加する必要がある場合は、addTemplate ユーティリティを使用できます。

import { defineNuxtModule, addTemplate } from "@nuxt/kit";

export default defineNuxtModule({
  setup(options, nuxt) {
    // ファイルは Nuxt の内部仮想ファイル システムに追加され、「#build/my-module-feature.mjs」からインポートできます。
    addTemplate({
      filename: "my-module-feature.mjs",
      getContents: () => 'export const myModuleFeature = () => "hello world !"',
    });
  },
});

型宣言の追加

ユーザーのプロジェクトに型宣言を追加することもできます (たとえば、Nuxt インターフェイスを拡張したり、独自のグローバル型を提供したりするため)。 このために、Nuxt は、テンプレートをディスクに書き込み、生成されたnuxt.d.tsファイルにテンプレートへの参照を追加する addTypeTemplateユーティリティを提供します。

モジュールが Nuxt によって処理される型を拡張する必要がある場合は、addTypeTemplate を使用してこの操作を実行できます:

import { defineNuxtModule, addTemplate, addTypeTemplate } from "@nuxt/kit";

export default defineNuxtModule({
  setup(options, nuxt) {
    addTypeTemplate({
      filename: "types/my-module.d.ts",
      getContents: () => `// Generated by my-module
        interface MyModuleNitroRules {
          myModule?: { foo: 'bar' }
        }
        declare module 'nitropack' {
          interface NitroRouteRules extends MyModuleNitroRules {}
          interface NitroRouteConfig extends MyModuleNitroRules {}
        }
        export {}`,
    });
  },
});

const template = addTemplate({
  /* template options */
});
nuxt.hook("prepare:types", ({ references }) => {
  references.push({ path: template.dst });
});

テンプレートの更新

テンプレート/仮想ファイルを更新する必要がある場合は、次のようにupdateTemplatesユーティリティを利用できます:

nuxt.hook('builder:watch', async (event, path) => {
  if (path.includes('my-module-feature.config')) { 
    // This will reload the template that you registered
    updateTemplates({ filter: t => t.filename === 'my-module-feature.mjs' })
  }
})

テスト

テストは、さまざまな設定を考慮してモジュールが期待どおりに動作することを確認するのに役立ちます。 このセクションでは、モジュールに対してさまざまな種類のテストを実行する方法を説明します。

ユニットと統合

エンドツーエンド

Nuxt Test Utilsは、エンドツーエンドの方法でモジュールをテストするのに役立つ頼りになるライブラリです。 これを採用するワークフローは次のとおりです:

• test/fixtures/*内で「フィクスチャ」として使用する Nuxt アプリケーションを作成します。
• テストファイル内でこのフィクスチャを使用して Nuxt をセットアップします
• @nuxt/test-utilsのユーティリティを使用してフィクスチャと対話します (ページのフェッチなど)
• このフィクスチャに関連するチェックを実行します (例: 「HTML には ... が含まれています」)
• リピート

実際には、フィクスチャは次のようになります:

// 1. 「fixture」として使用するNuxtアプリケーションを作成します
// ※fixtureとは、使いまわしをするテストデータのこと。
import MyModule from "../../../src/module";

export default defineNuxtConfig({
  ssr: true,
  modules: [MyModule],
});

// 1. 「fixture」として使用する Nuxt アプリケーションを作成する
import { describe, it, expect } from "vitest";
import { fileURLToPath } from "node:url";
import { setup, $fetch } from "@nuxt/test-utils";

describe("ssr", async () => {
  // 2. テストファイル内でこのfixtureを使用して Nuxt をセットアップします
  await setup({
    rootDir: fileURLToPath(new URL("./fixtures/ssr", import.meta.url)),
  });

  it("renders the index page", async () => {
    // 3. `@nuxt/test-utils` のユーティリティを使用してfixtureを呼び出し。
    const html = await $fetch("/");

    // 4. このfixtureに関連するチェックを実行します
    expect(html).toContain("<div>ssr</div>");
  });
});

// 5. リピート
describe("csr", async () => {
  /* ... */
});

Playground および外部でのマニュアルQA

開発時にモジュールをテストするためのプレイグラウンド Nuxt アプリケーションがあると、非常に便利です。 モジュール スターターは、その目的のために 1 つを統合します。

別の Nuxt アプリケーション（モジュールリポジトリの一部ではないアプリケーション）で、モジュールをローカルにテストすることができます。これを行うには、npm packコマンド、またはそれに相当するパッケージマネージャを使用して、モジュールから tarball を作成します。その後、テストプロジェクトで、package.jsonの packages にモジュールを追加できます。例: "my-module": "file:/path/to/tarball.tgz"。

その後、通常のプロジェクトと同様にmy-moduleを参照できるようになります。

ベストプラクティス

大きな力には大きな責任が伴います。 モジュールは強力ですが、アプリケーションのパフォーマンスと開発者のエクスペリエンスを向上させるために、モジュールを作成する際に留意すべきベスト プラクティスがいくつかあります。

Async モジュール

これまで見てきたように、Nuxt モジュールは非同期にすることができます。 たとえば、API を取得したり、非同期関数を呼び出したりする必要があるモジュールを開発したい場合があります。

ただし、Nuxt はモジュールがセットアップされるまで待機してから、次のモジュールに進み、開発サーバーやビルド プロセスなどを開始するため、非同期動作には注意してください。時間のかかるロジックは Nuxt フックに延期することをお勧めします。

常に公開されるインターフェースには常に接頭辞を付けてください

Nuxt モジュールは、他のモジュールや内部モジュールとの競合を避けるために、公開された設定、プラグイン、API、コンポーザブル、またはコンポーネントに明示的なプレフィックスを提供する必要があります。

理想的には、モジュール名をプレフィックスとして付ける必要があります (たとえば、モジュールが nuxt-foo の場合、<Button> と useBar() ではなく、<FooButton> と useFooBar() を公開します)。

TypeScript フレンドリー

Nuxt 3 には、最高の開発者エクスペリエンスを実現するファーストクラスの TypeScript 統合が備わっています。

型を公開し、TypeScript を使用してモジュールを開発することは、TypeScript を直接使用しない場合でもユーザーに利益をもたらします。

CommonJS 構文の回避

Nuxt 3 はネイティブ ESM に依存します。 詳細については、「ネイティブ ES モジュール」を参照してください。

ドキュメントモジュールの使用法

モジュールの使用法を Readme ファイルに文書化することを検討してください。

• このモジュールを使用する理由
• このモジュールの使い方は?
• このモジュールは何をするのでしょうか?

統合Webサイトとドキュメントにリンクすることは常に良い考えです。

StackBlitzデモ or ボイラープレート

モジュールと、モジュールの Readme に追加した StackBlitz を使用して最小限の再現を行うことをお勧めします。

これにより、モジュールの潜在的なユーザーがモジュールを試すための迅速かつ簡単な方法が提供されるだけでなく、問題が発生したときに送信できる最小限の複製を作成する簡単な方法も提供されます。

特定の Nuxt バージョンを宣伝しないでください

Nuxt 3、Nuxt Kit、およびその他の新しいツールは、前方互換性と後方互換性の両方を念頭に置いて作成されています。

エコシステムの断片化を回避し、Nuxt バージョンの制約を設定する場合は、meta.compatibility を使用することを優先するため、「X for Nuxt 3」ではなく「X for Nuxt」を使用してください。

スターターのデフォルト使用

モジュール スターターには、デフォルトのツールと設定のセット (ESLint 設定など) が付属しています。 モジュールをオープンソース化する予定がある場合は、これらのデフォルトを維持することで、モジュールが他の コミュニティモジュールと一貫したコーディング スタイルを共有できるようになり、他の人が貢献しやすくなります。

エコシステム

Nuxt Module エコシステムは、月間 1,500 万を超える NPM ダウンロードを表し、拡張機能とあらゆる種類のツールとの統合を提供します。 あなたもこのエコシステムの一員になることができます!

モジュールの種類

公式モジュールは、@nuxt/というプレフィックスが付いた (スコープされた) モジュールです (例: @nuxt/content)。 これらは、Nuxt チームによって積極的に作成および保守されています。 フレームワークと同様に、フレームワークを改善するためにコミュニティからの貢献を大歓迎です。

コミュニティ モジュールは、@nuxtjs/というプレフィックスが付けられた (スコープが設定された) モジュールです (例:@nuxtjs/tailwindcss)。これらは、コミュニティのメンバーによって作成および保守されている実証済みのモジュールです。 繰り返しになりますが、誰からの貢献も歓迎します。

サードパーティおよびその他のコミュニティ モジュールは、(多くの場合) プレフィックスnuxt- が付いたモジュールです。 誰でも作成でき、このプレフィックスを使用すると、これらのモジュールを npm で検出できるようになります。 これは、アイデアの下書きや試してみるのに最適な出発点です。

プライベート モジュールまたは個人モジュールは、独自のユースケースまたは会社のために作成されたモジュールです。 Nuxt で動作するために命名規則に従う必要はなく、多くの場合、npm 組織 (例: @my-company/nuxt-auth) の下でスコープされます。

コミュニティモジュールをリストする

どんなコミュニティモジュールでもモジュールリストに掲載されることが歓迎されます。掲載するには、nuxt/modules リポジトリで問題を開いてください。Nuxtチームは、掲載前にベストプラクティスを適用するお手伝いをすることができます。

nuxt-modules と @nuxtjs/ を結合する

モジュールを nuxt-modules に移行すると、いつでも誰かが助けてくれるので、私たちは力を合わせて 1 つの完璧なソリューションを作ることができます。

すでに公開されて動作しているモジュールをnuxt-modulesに移行したい場合は、nuxt/modules で問題を開いてください。

nuxt-modules に参加することで、コミュニティモジュールを@nuxtjs/ スコープの下で名前を変更し、そのドキュメント用にサブドメイン（例:my-module.nuxtjs.org）を提供できます。