【実務・中級編】npmとpnpmの「フック(hooks)」を使いこなす：インストール後のパッケージ修正を自動化する方法 – ビルド・パッケージ管理ツール生産性向上バイブル

依存関係の「負の遺産」を自動浄化せよ：pnpm `hooks` と `patch-package` で実現する恒久的な修正戦略

フロントエンド開発において、依存ライブラリのバグに遭遇した瞬間、多くのエンジニアが「`node_modules` を直接書き換えて動いた！」と安堵し、そのまま放置して数週間後に地獄を見るという経験をしているはずだ。

ライブラリのソースコードを直接改変するのは、ビルド環境において「爆弾」を埋め込むに等しい。なぜなら、その修正はCI環境で再現されず、同僚の環境とも同期されないからだ。

本稿では、テックリードとして、依存関係の外部的な欠陥を「自動的に修正し続ける」ための、堅牢でスケーラブルなエンジニアリング手法を伝授する。

—

なぜ「直接編集」が悪手なのか：アーキテクチャ的視点

`node_modules` はイミュータブル（不変）であるべきだ。パッケージマネージャは常に整合性を保とうとするため、`npm install` や `pnpm install` が走るたびに、あなたが書き換えたコードは容赦なく上書きされる。

我々が目指すべきは、「インストールのプロセス自体に修正ロジックを注入する」ことである。

—

1. pnpmの真骨頂：`.pnpmfile.cjs` による依存関係のオーバーライド

pnpmの最大の特徴は、`hooks` 機能がネイティブで提供されている点だ。これを使えば、インストールプロセス中にパッケージのメタデータや依存関係を動的に書き換えることができる。

ベストプラクティス：`.pnpmfile.cjs` の設定

例えば、特定のパッケージが古い依存関係を要求しており、それが原因でセキュリティ警告が出ている場合や、バグがある場合に有効だ。

// .pnpmfile.cjs
// インストール時に依存関係のグラフをフックし、強制的にバージョンを差し替える
function readPackage(pkg, context) {
// 特定のライブラリの依存関係を強制的にアップデート
if (pkg.name === ‘legacy-ui-library’ && pkg.dependencies[‘lodash’]) {
context.log(‘Patching lodash version for legacy-ui-library’);
pkg.dependencies[‘lodash’] = ‘^4.17.21’; // 脆弱性のある古いバージョンを強制更新
}
return pkg;
}

module.exports = {
hooks: {
readPackage // フックをエクスポート
}
};

この設定ファイルをプロジェクトルートに置くだけで、`pnpm install` が走るたびに整合性が保たれる。チーム全員が同じフックを通るため、環境差分によるバグが一切発生しなくなる。

—

2. 実践的パッチ戦略：`patch-package` によるソースコードの動的修正

依存関係のライブラリそのものにバグがあり、修正PRを送ってもマージされない、あるいは即時反映が必要な場合、`patch-package` が最強の武器となる。

ステップ1：ソースの修正とパッチの生成

まず、`node_modules` 内の該当ファイルを修正し、以下のコマンドを打つ。

修正したパッケージ名に対してパッチを生成する
npx patch-package

これにより、`patches/` ディレクトリに差分ファイルが生成される。この `patches/` フォルダをGit管理下に置くのが鉄則だ。

ステップ2：CIでの自動適用

`package.json` の `postinstall` スクリプトに仕込んでおくことで、CI環境やメンバーのローカル環境で自動的にパッチが適用される。

{
“scripts”: {
“postinstall”: “patch-package”
// インストールが完了するたびに、patchesディレクトリの内容をnode_modulesに自動適用する
}
}

—

チーム開発を加速させる「テックリードの心得」

ここからは、ツールを使いこなすための付加価値テクニックを共有する。

1. 隠れた神コマンド・ショートカット

`pnpm` を使うなら、以下のエイリアスとコマンドは指に覚え込ませろ。

`pnpm up -i`: インタラクティブモードで依存関係をアップデート。どのライブラリがどの程度バージョンアップするのかをUIで見ながら選別できる。
`pnpm why `: なぜそのパッケージがインストールされているのか、依存関係のツリーを逆引きする。不要な巨大ライブラリを特定する際に必須。

2. チーム開発における設定の共有化ルール

設定ファイル（`.pnpmfile.cjs` や `patches/`）は、「コードレビューの対象」とする。
パッチを作成した際は、必ず「なぜその修正が必要なのか」をパッチのファイル名やPRのコメントに記載すること。将来、ライブラリが更新された際、そのパッチが不要になったかどうかを判断する唯一の根拠になるからだ。

3. VS Code 神プラグイン

[Import Cost](https://marketplace.visualstudio.com/items?itemName=wix.vscode-import-cost): インポートしたパッケージのサイズをエディタ上で表示する。重い依存関係を可視化することで、無意識な肥大化を防ぐ。
[Version Lens](https://marketplace.visualstudio.com/items?itemName=pflannery.vscode-versionlens): `package.json` 上で最新バージョンとの差分を確認し、ワンクリックで更新できる。

—

まとめ：運用を自動化し、エンジニアは「本質」へ

ライブラリのバグに振り回され、手作業で修正を繰り返すのは時間の浪費だ。
`pnpm hooks` や `patch-package` を活用し、「インフラ（環境）が勝手に正しい状態を維持してくれる」という環境を構築すること。それが、チームの生産性を底上げし、プロダクトの品質を担保する唯一の道である。

今すぐ `patches/` ディレクトリを作り、Git管理下に置こう。それが、あなたのチームが「一歩先」へ行くための第一歩だ。