ロガー

意味を持った形式でコンソールメッセージを整形する、カプセル化されたロガー。

Docusaurus エコシステム内のパッケージ作者には、このパッケージを使って統一されたログフォーマットを提供することが推奨されています。

API

このパッケージは、logger という単一のオブジェクトをデフォルトエクスポートとして提供しています。 logger は以下のプロパティを持っています：

• 便利なカラーパレット。
  • 赤
  • 黄
  • 緑
  • 太字
  • 薄め
• フォーマッター。 これらの関数はすべて、(msg: unknown) => string というシグネチャ（引数と戻り値の型）を持っています。 なお、これらの関数の実装は保証されていません。 重要なのは実装の詳細ではなく、それらが持つ意味（セマンティクス）です。
  • ``path\：ファイルパスを整形します。
  • url：URLを整形します。
  • name：識別子を整形します。
  • code：コードスニペットを整形します。
  • subdue：テキストの強調を抑えます。
  • num：数値を整形します。
• interpolate 関数。 これはテンプレートリテラルタグです。 構文は以下の通りです。
• ログ出力用の関数。 すべてのログ関数は、通常の関数として（console.log ファミリーに似ていますが、引数は1つだけ受け取ります）使うことも、テンプレートリテラルタグとして使うこともできます。
  • info：情報を出力します。
  • warn：注意が必要な警告を出力します。
  • error：重大な問題を示すエラーを出力します（必ずしもプログラムを停止するわけではありません）。
  • success：成功メッセージを出力します。
• report 関数。 ReportingSeverity の値（ignore、log、warn、throw）を受け取り、その重大度に応じてメッセージを報告します。

error フォーマッターについての注意事項

error メッセージは、プログラムが停止しない場合でも、混乱を招く恐れがあるので注意してください。 ユーザーはログを確認して [ERROR] を見つけると、ビルドが成功していても何か問題が起きていると誤解してしまいます。 使用は控えめにしてください。

Docusaurus は、エラーをスローする直前にメッセージを出力する場合や、ユーザーが onBrokenLink などの報告レベルを "error" に設定している場合にのみ、logger.error を使用します。

加えて、warn と error は、より注意を引くためにメッセージ全体を色付けします。 エラーに関する大きなヘルプテキストを表示する場合は、logger.info を使うのが適しています。

:::

テンプレートリテラルタグの使用方法

テンプレートリテラルタグは、埋め込まれたテンプレート文字列や式を評価します。 interpolate は新しい文字列を返しますが、他のログ関数はその結果を出力します。 以下は典型的な使い方の例です：

import logger from '@docusaurus/logger';

logger.info`Hello name=${name}! あなたは ${money} 円持っています。 ここにあるのは ${
  items.length > 1 ? 'items' : 'item'
} on the shelf: ${items}
To buy anything, enter code=${'buy x'} where code=${'x'} is the item's name; to quit, press code=${'Ctrl + C'}.`;

埋め込み式の直前には、オプションで [a-z]+= という形式のフラグを付けることができます。これは、いくつかの小文字アルファベットに続いてイコール（=）があり、その直後に埋め込み式が続く形です。 埋め込み式の前にフラグが付いていない場合は、その式の値がそのまま出力されます。 フラグが付いている場合は、指定されたフォーマッターのいずれかを使って整形されます：

• path=: path
• url=: url
• name=: name
• code=: code
• subdue=: subdue
• number=: num

もし式の値が配列の場合は、\n- ${array.join('\n- ')}\n の形式で整形されます（先頭に自動で改行が入る点に注意してください）。 各要素は個別にフォーマットされ、箇条書きの「・」自体はフォーマットされません。 したがって、上記のメッセージは以下のように表示されます：