pnpm v11 への移行とワークスペース設定の刷新

pnpm v11 へバージョンアップし、pnpm-workspace.yaml に設定を集約したことで、Windows 環境でのシム問題が解消され、依存管理が一元化されました。

背景

pnpm v9 では Windows 環境特有のシム問題が統合テストで頻発し、開発者体験を阻害していました。PR の説明によれば、pnpm/action-setup を最新版に更新し、設定を pnpm-workspace.yaml に移行することでこの障壁を取り除くことが目的です。さらに、pnpm v11 では package.json の pnpm フィールドが無効になるため、設定の一本化が必須となっていました。.npmrc に記載されていた node-linker=hoisted も削除され、リンク方式をワークスペースファイルで管理できるようになりました。

技術的な変更

CI ワークフロー では全ての .github/workflows/*.yml が pnpm/action-setup@v6.0.9 に統一され、環境変数 PNPM_VERSION が '11.9.0' へ変更されました。これに伴い pnpm install がデフォルトでワークスペースを認識し、テスト実行時の --ignore-workspace オプションが除去されました。

ワークスペース設定 は pnpm-workspace.yaml に大幅に拡張され、patchedDependencies 、onlyBuiltDependencies 、allowBuilds が新たに記述されています。これにより特定パッケージのビルドやパッチ適用を明示的に許可でき、全体の依存解決が一元管理されます。

ユーティリティコード では integrations/utils.ts が yaml パッケージをインポートし、リポジトリルートの pnpm-workspace.yaml を読み込んで解析するロジックが追加されました。またテスト設定に retry オプションが導入され、CI 環境での再実行回数を制御できます。

テストスクリプト 全般で npx 系コマンドが pnpm exec 系へ置き換えられ、Windows 環境でのシム書き換え競合を回避するため IS_WINDOWS 判定によるガードが実装されています。integrations/vite/index.test.ts では allowBuilds 設定を利用し、es5‑ext のビルドを許可しています。integrations/vite/nuxt.test.ts では pnpm-workspace.yaml に overrides を記述し、nuxi のバージョン固定を行っています。

パッケージマネージャ設定 はトップレベル package.json の packageManager が pnpm@11.9.0 に更新され、従来の pnpm フィールドが削除されました。playgrounds 配下の各 package.json でも同様に pnpm フィールドが除去されています。

ロックファイルとビルドスクリプト では pnpm-lock.yaml のパッチ記述が patchedDependencies セクションへ移行され、scripts/pack-packages.mjs が bundledDependencies を持つパッケージのみ --config.node-linker=hoisted オプションを付与してパックするロジックを追加しました。これにより hoisted リンカーを全体に適用せず、必要なパッケージだけに限定して使用できます。

設計判断

設定の集中化 は pnpm フィールドを廃止し、全てのワークスペース関連設定を pnpm-workspace.yaml に移行した点です。これにより将来的なバージョンアップ時の破壊的変更リスクが低減し、リポジトリ全体の構成が一元管理可能になります。

ビルドスコープの限定 は、onlyBuiltDependencies と allowBuilds を用いてビルドが必要なパッケージだけを明示的に許可する方針です。scripts/pack-packages.mjs の条件分岐により、bundledDependencies を持つパッケージのみ hoisted リンカーを使用する設計となり、CI の安定性とキャッシュ効率が向上します。

Windows 向け回避策 は、utils.ts に組み込まれた IS_WINDOWS 判定と pnpm exec upgrade のスキップロジックです。pnpm v11 の Windows でのシム書き換えバグを回避し、テスト実行の堅牢性を確保しています。

まとめ

pnpm v11 への移行に伴い、設定を pnpm-workspace.yaml に集約し、CI・テスト・ビルドスクリプトを新バージョンに合わせて調整しました。これにより Windows 環境の安定性が向上し、設定の一元管理による保守性が大幅に改善されています。