Astroプロジェクトでよく使われるastro-iconは便利ですが、最近いくつかのエラーが発生しています。このガイドでは、そのエラーの原因と具体的な解決方法をわかりやすく説明します。

エラーの原因と対策

エラーメッセージの例

astro-iconをインストールし、npm run devを行うと、下記のようにエラーが出てしまいました、、、

Error when evaluating SSR module [...]/astro.config.mjs: failed to import "astro-icon"
SyntaxError: The requested module 'cheerio' does not provide an export named 'default'
    at ModuleJob._instantiate (node:internal/modules/esm/module_job:124:21)
    at async ModuleJob.run (node:internal/modules/esm/module_job:190:5)

エラーの原因

このエラーが発生する主な原因は次の通りです。

  • 依存関係の不一致 astro-iconは@iconify/toolsに依存しており、その中で使用されるcheerioのバージョンに問題があることがあります。
  • モジュールシステムの変更 cheerioの新しいバージョンでは、ECMAScript Modulesの取り扱いが変わったため、エクスポートの形式が変わっています。
  • バージョンの衝突 プロジェクト内で異なるバージョンのcheerioがインストールされている可能性があります。

解決策

package.jsonで依存関係を上書き

package.jsonを以下のように変更して、特定のバージョンの@iconify/toolsを強制的に使用します。 私はこちらの方法で解決しました。

{
  "overrides": {
    "astro-icon": {
      "@iconify/tools": "^4.0.5"
    }
  }
}

これで@iconify/toolsのバージョンが4.0.5以上に固定され、新しいcheerioと互換性がある状態になります。

@iconify/toolsを直接更新

別の方法として、@iconify/toolsを最新バージョンに更新する手もあります。

npm install @iconify/tools@latest --save-dev

これにより、プロジェクト全体で最新のツールセットを使用することができ、互換性の問題を回避できます。

Cheerioのバージョンを指定

場合によっては、cheerioのバージョンを直接指定する必要があります。

{
  "resolutions": {
    "cheerio": "1.0.0-rc.12"
  }
}

注意: この設定はYarnを使用している場合に機能し、npmの場合はoverridesを使用します。

実施手順

  1. package.jsonの修正 上記の解決策に従って、package.jsonを修正します。

  2. 依存関係のクリーンアップ node_modulesとpackage-lock.jsonを削除します。 手動削除でも問題ありません。

    rm -rf node_modules package-lock.json

    これで古い依存関係が削除されます。

  3. キャッシュのクリア（オプション）

    npm cache clean --force

  4. 依存関係の再インストール

    npm install

  5. プロジェクトの再起動

    npm run dev

これでエラーが解消されているか確認します。

その他のヒント

  • Node.jsバージョンの確認 Node.jsのバージョンを確認し、必要に応じてアップグレードしてください。推奨されるバージョンは v18.17.1 以上です。

  • 依存関係ツリーの確認 npm ls cheerioコマンドで、どのバージョンのcheerioがインストールされているか確認できます。

  • 脆弱性の修正 npm audit fixで脆弱性を修正し、問題が深刻な場合はnpm audit fix --forceを使用してください。