Font Awesome アイコンのセルフホスティングを簡単にする新API

setIconPath() / getIconPath() の追加により、デフォルトアイコンライブラリをFont Awesome CDNからセルフホスト環境へ切り替える手段が公式に提供されました。上級者向けには getIconFolder() のエクスポートも追加され、カスタムリゾルバーの実装にも対応しています。

背景

Web Awesomeのデフォルトアイコンライブラリは、Font AwesomeのCDNからSVGを取得する設計になっていました。#1423 で報告されているように、Font Awesome Pro+ユーザーを含む多くのユーザーがアイコンをセルフホストしたいという要望を持っていましたが、公式なAPIが存在しなかったため、ユーザーは registerIconLibrary() を使って独自のリゾルバーをゼロから実装する必要がありました。

Font Awesomeのダウンロードアーカイブには、solid/・regular/・brands/ などのサブフォルダを持つ svgs ディレクトリが含まれています。しかし、このフォルダ構造を正しく解決するロジック（family/variantからフォルダ名へのマッピング）はライブラリ内部に閉じており、ユーザーが再利用できませんでした。このPRはその制約を取り除くものです。

技術的な変更

setIconPath() / getIconPath() の追加

base-path.ts に iconPath というモジュールスコープの変数が追加され、アイコンの解決先パスを保持するようになりました。

変更後の packages/webawesome/src/utilities/base-path.ts（追加部分）:

let iconPath = '';

export function setIconPath(path: string) {
  iconPath = path;
}

export function getIconPath() {
  return iconPath.replace(/\/$/, '');
}

getIconPath() は末尾のスラッシュを正規化して返します。これは既存の getBasePath() と同じパターンであり、設計の一貫性が保たれています。

デフォルトライブラリのURL解決ロジックの変更

library.default.ts の getIconUrl() 関数が変更され、iconPath が設定されている場合はCDNの代わりにそのパスを使用するようになりました。

変更前:

function getIconUrl(name: string, family: string, variant: string) {
  const kitCode = getKitCode();
  const isPro = kitCode.length > 0;
  let folder = 'solid';
  // ... folderの決定ロジック ...

  // Use the default CDN
  return isPro
    ? `https://ka-p.fontawesome.com/releases/v${FA_VERSION}/svgs/${folder}/${name}.svg?token=${encodeURIComponent(kitCode)}`
    : `https://ka-f.fontawesome.com/releases/v${FA_VERSION}/svgs/${folder}/${name}.svg`;
}

変更後:

export function getIconFolder(_name: string, family: string, variant: string) {
  let folder = 'solid';
  // ... folderの決定ロジック（同一） ...
  return folder;
}

function getIconUrl(name: string, family: string, variant: string) {
  const folder = getIconFolder(name, family, variant);
  const iconBase = getIconPath();

  if (iconBase) {
    return `${iconBase}/${folder}/${name}.svg`;
  }

  const kitCode = getKitCode();
  const isPro = kitCode.length > 0;

  return isPro
    ? `https://ka-p.fontawesome.com/releases/v${FA_VERSION}/svgs/${folder}/${name}.svg?token=${encodeURIComponent(kitCode)}`
    : `https://ka-f.fontawesome.com/releases/v${FA_VERSION}/svgs/${folder}/${name}.svg`;
}

family/variantからフォルダ名を決定していたロジックが getIconFolder() として切り出され、export されました。getIconUrl() はこれを呼び出す形にリファクタリングされています。

パブリックAPIへのエクスポート追加

webawesome.ts のエントリーポイントに3つのシンボルが追加されました。

export { getIconFolder } from './components/icon/library.default.js';
export { getBasePath, getIconPath, getKitCode, setBasePath, setIconPath, setKitCode } from './utilities/base-path.js';

これにより、setIconPath・getIconPath・getIconFolder の3関数が /dist/webawesome.js からインポート可能になります。

設計判断

iconPath が未設定の場合は従来のCDN動作にフォールバックする 設計が採用されました。getIconPath() が空文字列を返す場合（デフォルト状態）、getIconUrl() はkitCodeの有無に応じたCDN URLを引き続き構築します。これにより、setIconPath() を呼ばない既存ユーザーへの影響はゼロです。

getIconFolder() を export する判断も注目に値します。フォルダ名の決定ロジックはFamily（classic/sharpなど）とVariant（solid/regularなど）の組み合わせによる複雑な条件分岐を含みます。このロジックを内部に閉じたままカスタムリゾルバーの例だけを提示する選択肢もありましたが、ヘルパー関数として公開することで、ユーザーが独自のリゾルバーを registerIconLibrary() と組み合わせて実装する際に、同じロジックを再実装しなくて済むようになっています。

setIconPath() はコンポーネントのロード前に呼ばれることを想定しており、その旨がJSDocコメントに明記されています。setBasePath() と同様の事前設定パターンに倣っており、ライブラリの設定APIとして一貫したインターフェースを提供しています。

まとめ

本PRは、既存のアーキテクチャを大きく変えることなく、内部ロジックの分離とシンプルなパス変数の追加によってセルフホスティングを実現した変更です。getIconFolder() の公開により、setIconPath() では対応できない高度なユースケース（バージョンクエリパラメータの付与など）にも、同じロジックを再利用したカスタムリゾルバーで対応できる拡張性が確保されています。