pnpm v11 で lefthook が動かないときに見直す pnpm-workspace.yaml の allowBuilds 設定

どうも！オペ部の西村祐二です！

pnpm を v11 系に上げたあと、git commit 時に lefthook のフックが動かなくなり、pnpm exec lefthook を直接叩いても [ERR_PNPM_IGNORED_BUILDS] で落ちる現象に遭遇しました。

pnpm v10 系で動いていた package.json の pnpm.onlyBuiltDependencies 設定が、v11 では仕様変更によって読まれなくなったのが原因でした。同じ症状で困っている方の助けになれば嬉しいです。

先に解決方法

プロジェクトルートに pnpm-workspace.yaml を置き、allowBuilds で lefthook を許可します。

allowBuilds:
  lefthook: true

そのうえで pnpm install を実行し直すと、lefthook の postinstall が走り .git/hooks/pre-commit が自動生成されます。node_modules がすでに作られている環境では、念のため rm -rf node_modules してから入れ直すと確実です。

遭遇したエラー

[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: lefthook@1.13.6

Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.

症状:

• pnpm install 自体は通る（ように見える）が、上記のエラーがログの最後に出る
• .git/hooks/ 配下に pre-commit が作られず、sample ファイルしか入っていない
• pnpm exec lefthook version も同じエラーで exit code 1 になる
• git commit してもフックが何も動かないまま通ってしまう

いつ発生するか:

• pnpm v11 系で lefthook を依存に含めて pnpm install したとき
• v10 までの package.json 内の pnpm.onlyBuiltDependencies 設定をそのまま持ち込んだとき

やろうとしたこと

ローカル開発で git commit のたびに lint と型チェックを走らせるために、devDependencies に lefthook を入れて pnpm install するだけ、という単純な構成を想定していました。

環境:

• OS: macOS
• パッケージマネージャ: pnpm 11.8.0
• Git フックマネージャ: lefthook 1.13.6

試したこと

package.json に pnpm.onlyBuiltDependencies を書く（v10 までの定番）

やったこと:

pnpm v10 時代の定石として、許可するパッケージを package.json に列挙する方法を試しました。

{
  "name": "blog-verify-pnpm-v11-lefthook",
  "devDependencies": {
    "lefthook": "^1.13.0"
  },
  "pnpm": {
    "onlyBuiltDependencies": ["lefthook"]
  }
}

pnpm install を実行したところ、次の警告が出ました。

[WARN] The "pnpm" field in package.json is no longer read by pnpm.
The following keys were ignored: "pnpm.onlyBuiltDependencies".
See https://pnpm.io/settings for the new home of each setting.

結果:
解決しなかった

なぜダメだったか:

pnpm v11 では package.json の pnpm フィールドそのものが読まれなくなっています。設定はあるのに反映されないため、ERR_PNPM_IGNORED_BUILDS がそのまま出続けます。警告を見逃すと「設定したのに動かない」状態でハマります。

最終的にうまくいった方法

最終的には、pnpm v11 で導入された pnpm-workspace.yaml の allowBuilds 設定で解決しました。

解決方法の詳細

ステップ1: プロジェクトルートに pnpm-workspace.yaml を作る

ワークスペースを使っていない単一プロジェクトでも、v11 ではこのファイルが pnpm の設定置き場として標準になっています。

allowBuilds:
  lefthook: true

キーはパッケージ名、値は true（実行を許可）/ false（明示的に拒否）の真偽値です。v10 までのように許可するパッケージ名の配列を渡す形ではない点に注意してください。

ステップ2: 必要なら package.json 側の旧設定を削除する

package.json に残った pnpm.onlyBuiltDependencies などは v11 では無視されますが、警告が出続けるため削除しておくと分かりやすいです。

{
  "name": "your-app",
  "devDependencies": {
    "lefthook": "^1.13.0"
  }
}

ステップ3: node_modules を作り直して pnpm install を再実行する

postinstall が一度スキップされた状態の node_modules をそのまま使うと、再インストールしても postinstall が走らないことがあるため、念のため node_modules を消してからインストールし直します。

rm -rf node_modules
pnpm install

実行すると、postinstall が動いてフックが同期されるログが流れます。

.../node_modules/lefthook postinstall$ node postinstall.js
.../node_modules/lefthook postinstall: sync hooks: ✔️ (pre-commit)
.../node_modules/lefthook postinstall: Done

devDependencies:
+ lefthook 1.13.6

Done in 1.1s using pnpm v11.8.0

ステップ4: 動作確認

pnpm exec lefthook version がバージョンを返し、.git/hooks/pre-commit が生成されていれば正常です。

$ pnpm exec lefthook version
1.13.6

$ ls -la .git/hooks/pre-commit
.rwxr-xr-x@ 2.0k ... .git/hooks/pre-commit

試しに lefthook.yml を置いて git commit してみると、フックが発火することが確認できます。

pre-commit:
  commands:
    echo:
      run: echo "lefthook pre-commit ran"

╭───────────────────────────────────────╮
│ 🥊 lefthook v1.13.6  hook: pre-commit │
╰───────────────────────────────────────╯
┃  echo ❯

lefthook pre-commit ran

summary: (done in 0.04 seconds)
✔️ echo (0.01 seconds)

なぜ解決したのか

根本原因:

pnpm v11 のリリースノート（pnpm v11.0.0 release notes）に書かれているとおり、次の2つの破壊的変更がこの問題を引き起こしていました。

1. 設定の置き場所が変わった: 認証・レジストリ以外の設定は .npmrc や package.json の pnpm フィールドからは読まれなくなり、pnpm-workspace.yaml（プロジェクトローカル）または ~/.config/pnpm/config.yaml（グローバル）に書く形に変わりました。
2. onlyBuiltDependencies が削除され allowBuilds に置き換わった: 同時に onlyBuiltDependenciesFile / neverBuiltDependencies / ignoredBuiltDependencies / ignoreDepScripts も削除されています。新しい allowBuilds はパッケージ名パターンをキーとする真偽値マップです。デフォルトでは依存パッケージのビルドスクリプトはすべて拒否される挙動になりました。

なぜこの方法で解決したのか:

lefthook は postinstall でプラットフォーム別バイナリの解決と .git/hooks/pre-commit への書き出しを行う設計です。これは pnpm の Lifecycle Scripts ドキュメントに整理されている「ビルドスクリプト」のひとつにあたります。

v11 では allowBuilds で明示的に許可されたパッケージしか postinstall を実行できません。そのため allowBuilds: { lefthook: true } を pnpm-workspace.yaml に書くと lefthook の postinstall が動き、フックが同期されるようになりました。

ハマったポイント

1. onlyBuiltDependencies で検索すると古い情報ばかり出てくる

   • v10 までの記事や Stack Overflow の回答は今もそのまま onlyBuiltDependencies を案内しているものが多く、v11 のリリースノートを直接見ないと新しいキー名（allowBuilds）に辿り着きにくい状態でした。

2. 「単一プロジェクトなのに pnpm-workspace.yaml ？」という違和感

   • 名前から workspace 機能専用のファイルに見えますが、v11 ではプロジェクトローカル設定の置き場所として一般化されているため、ワークスペースを使っていなくても置く必要があります。

3. CI で --frozen-lockfile を使っていても止まらない

   • pnpm install --frozen-lockfile で通ってしまうため、CI 上では lefthook が動かない状態のまま PR がマージされる可能性があります。pnpm-workspace.yaml を Git 管理に入れて、ローカルと CI で挙動を揃えておく必要があります。

まとめ

pnpm v11 系では、lefthook のように postinstall を前提とするツールは、明示的に pnpm-workspace.yaml の allowBuilds で許可しないと動きません。アップグレード時は設定ファイルの場所とキー名の両方を見直しましょう。

同じく postinstall でバイナリ取得や hook 登録を行うツール（husky などの hook 系や、ネイティブバイナリを取得するツールチェーン全般）も同じ確認が必要です。リリースノートの Security & Build Defaults セクションも読んでおくと、同種のハマりを避けられます。

誰かの参考になれば幸いです。

参考リンク:

• pnpm v11.0.0 リリースノート
• pnpm Settings ドキュメント
• pnpm Lifecycle Scripts ドキュメント
• lefthook 公式サイト
• evilmartians/lefthook #1439 - npm RFC #868 will block this package's install script by default
• evilmartians/lefthook #760 - postinstall does not get executed with pnpm