WooCommerce の拡張プラグインの最新版のサンプルプログラムのエラーの対策

WooCommerce では開発初心者向けに以下のページで簡単に最初のプラグイン構築のテストができるようになっています。

こちらは、非常に便利で参考になるのですが、まあほとんどのタイミングでエラーが出て簡単には開発環境が作れません。（T_T)
2025年9月14日現在でのエラー対応を書いておきます。

そもそものエラー原因は？

npx @wordpress/create-block -t @woocommerce/create-woo-extension my-extension-name

基本的にローカルの開発環境の設定が完了していたら上記のコードで開発環境が出来るはず（理想的には）なのですが、以下のようなエラーが発生します。

Warning: Failed to install dependencies:
Command failed with exit code 1: npm install
npm error code ERESOLVE
npm error ERESOLVE could not resolve
npm error
npm error While resolving: my-extension-name2@0.1.0
npm error Found: react@17.0.2
npm error node_modules/react
npm error   peer react@"^17.0.2" from @woocommerce/components@12.3.0
npm error   node_modules/@woocommerce/components
npm error     @woocommerce/components@"latest" from the root project
npm error   peer react@"17.0.2" from react-dom@17.0.2
npm error   node_modules/react-dom
npm error     peer react-dom@"^17.0.2" from @woocommerce/components@12.3.0
npm error     node_modules/@woocommerce/components
npm error       @woocommerce/components@"latest" from the root project
npm error   1 more (@wordpress/data)
npm error
npm error Could not resolve dependency:
npm error dev @wordpress/scripts@"latest" from the root project
npm error
npm error Conflicting peer dependency: react@18.3.1
npm error node_modules/react
npm error   peer react@"^18.0.0" from @wordpress/scripts@30.23.0
npm error   node_modules/@wordpress/scripts
npm error     dev @wordpress/scripts@"latest" from the root project
npm error
npm error Fix the upstream dependency conflict, or retry
npm error this command with --force or --legacy-peer-deps
npm error to accept an incorrect (and potentially broken) dependency resolution.

もし、上記以外のエラーの場合は別の原因なので、それは別途調べてください。ちなみに、こちらはエラーの一部で、本来はもっとエラー表示されますが、基本的に同じ原因のエラーです。

で、このエラーの意味はシンプルに説明すると以下です。

1. @woocommerce/components@12.3.0 → React 17.0.2 を要求
2. @wordpress/scripts@30.23.0 → React 18.3.1 を要求

ということで、React のバージョン競合による依存関係の解決エラーです。
WooCommerce のコンポーネントがまだ React 17 を使用している一方で、WordPress の最新スクリプトは React 18 に移行しているため、npm が依存関係を解決できない状況です。

ですが、本当のところは、2025年3月時点で12.3.0ですでに React 18.3 に対応は完了しているのです。

これって、多分、@woocommerce/components@12.3.0の宣言バグだと思うんですよね？ちょっと時間を見つけて、こちらの対応をコアのコントリビュートしようかなと思っているところです。

ただ、現時点では大丈夫と言われても、宣言が間違っているので、エラー対応をしないといけないという現状です。

解決方法

--legacy-peer-deps オプションを使用

bash

# プロジェクトディレクトリに移動
cd /Users/shoheitanaka/Dev/my-extension-name

# 依存関係をクリーンアップ
rm -rf node_modules package-lock.json

# legacy-peer-deps オプションでインストール
npm install --legacy-peer-deps

これで、少し時間もかかりますし、Warningも出ますが、開発はできるようになります。

あと、念のために今後も同じ問題を避けるため、プロジェクトに設定を追加：

bash

# .npmrc ファイルを作成
echo "legacy-peer-deps=true" > .npmrc

ただ、これは、バージョンが対応できたかどうかなどが分かりにくくなる点もあるので、やらなくてもいいかなと思います。

インストール時の警告内容

インストール時に以下のエラーが出ますが、基本的に開発環境では大丈夫です。

1. EBADENGINE 警告: 無視して問題ありません
2. deprecated 警告: 開発には影響しません
3. vulnerabilities 脆弱性: 開発環境では通常問題ありませんが、本番デプロイ前には対処を検討

まあ、これでインストールが終わったら、npm run build 等で開発を開始できるようになります。