プラグイン

Starlightのプラグインにより、Starlightの設定、UI、および動作をカスタマイズできます。このリファレンスページでは、プラグインがアクセス可能なAPIについて説明します。

Starlightのプラグインを使用する方法について、詳しくは設定方法のリファレンスを参照してください。また、利用可能なプラグインの一覧については、プラグインショーケースを確認してください。

API早見表

Starlightのプラグインは次の構造をもちます。各プロパティとフックパラメータの詳細については、以下を参照してください。

interface StarlightPlugin {
  name: string;
  hooks: {
    setup: (options: {
      config: StarlightUserConfig;
      updateConfig: (newConfig: StarlightUserConfig) => void;
      addIntegration: (integration: AstroIntegration) => void;
      astroConfig: AstroConfig;
      command: 'dev' | 'build' | 'preview';
      isRestart: boolean;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
  };
}

`name`

type: string

プラグインには、自身を説明する一意の名前を指定する必要があります。名前は、このプラグインに関連するログメッセージを出力するときに使用されます。また、あるプラグインの存在を検出するために使用される場合もあります。

`hooks`

フックは、Starlightが特定のタイミングでプラグインコードを実行するために呼び出す関数です。現在、Starlightはsetupフックのみサポートしています。

`hooks.setup`

プラグインのセットアップ関数は、Starlightが（astro:config:setupインテグレーションフックにおいて）初期化される際に呼び出されます。setupフックは、Starlightの設定を更新したり、Astroのインテグレーションを追加したりするために使用できます。

このフックは、以下のオプションとともに呼び出されます。

`config`

type: StarlightUserConfig

ユーザーが提供したStarlightの設定の、読み取り専用の複製です。この設定は、現在のプラグインより前に置かれた他のプラグインによって更新されている可能性があります。

`updateConfig`

type: (newConfig: StarlightUserConfig) => void

ユーザーが提供したStarlightの設定を更新するためのコールバック関数です。上書きしたいルートレベルの設定キーを指定します。ネストされた設定値を更新するには、ネストされたオブジェクトの全体を指定する必要があります。

既存の設定オプションをオーバーライドせず拡張するには、既存の値を新しい値へと展開します。以下の例では、config.socialを新しいsocialオブジェクトに展開し、既存の設定に新しいsocialメディアアカウントを追加しています。

export default {
  name: 'add-twitter-plugin',
  hooks: {
    setup({ config, updateConfig }) {
      updateConfig({
        social: {
          ...config.social,
          twitter: 'https://twitter.com/astrodotbuild',
        },
      });
    },
  },
};

`addIntegration`

type: (integration: AstroIntegration) => void

プラグインが必要とするAstroのインテグレーションを追加するためのコールバック関数です。

以下の例では、プラグインはまずAstroのReactインテグレーションが設定されているかどうかを確認し、設定されていない場合はaddIntegration()を使用して追加します。

import react from '@astrojs/react';

export default {
  name: 'plugin-using-react',
  hooks: {
    setup({ addIntegration, astroConfig }) {
      const isReactLoaded = astroConfig.integrations.find(
        ({ name }) => name === '@astrojs/react'
      );

      // まだロードされていない場合のみ、Reactインテグレーションを追加します。
      if (!isReactLoaded) {
        addIntegration(react());
      }
    },
  },
};

`astroConfig`

type: AstroConfig

ユーザーが提供したAstroの設定の、読み取り専用の複製です。

`command`

type: 'dev' | 'build' | 'preview'

Starlightを実行するために使用されたコマンドです。

dev - プロジェクトはastro devにより実行されています
build - プロジェクトはastro buildにより実行されています
preview - プロジェクトはastro previewにより実行されています

`isRestart`

type: boolean

開発サーバーが起動したときはfalse、リロードがトリガーされたときはtrueとなります。再起動が発生するよくある理由としては、開発サーバーが実行されている間にユーザーがastro.config.mjsを編集した場合などがあります。

`logger`

type: AstroIntegrationLogger

ログを書き込むために使用するAstroインテグレーションロガーのインスタンスです。すべてのログメッセージは、プラグイン名が接頭辞として付加されます。

export default {
  name: 'long-process-plugin',
  hooks: {
    setup({ logger }) {
      logger.info('時間が掛かる処理を開始します…');
      // 何らかの時間が掛かる処理…
    },
  },
};

上記の例では、指定されたinfoメッセージを含むメッセージがログに出力されます。

[long-process-plugin] 時間が掛かる処理を開始します…