投稿日:2026/11/18
更新日:2026/11/18

pnpm を 10 から 12 へ上げたとき、pnpm-workspace.yaml に設定が一気に増えた。なぜここに書くのか、allowBuilds とは何かを整理したメモ(pnpm の公式ドキュメントと v11.0.0 のリリースノートを 2026-11-18 に確認)。pnpm-workspace.yaml には「ワークスペースの定義」と「pnpm の設定ファイル」の2つの役割があり、pnpm 11 からは後者の役割が必須になった。
pnpm-workspace.yaml の役割は2つ。どのフォルダがパッケージかを教える(ワークスペースの定義)と、pnpm の動作を決める設定を書く(設定ファイル)package.json の pnpm フィールドは読まれず、.npmrc は認証とレジストリの設定しか読まれない。設定は pnpm-workspace.yaml に書く。パッケージが1つだけのプロジェクトでも置くallowBuilds は、依存パッケージが install 時に動かすスクリプトを パッケージごとに実行するか・しないか 決める表allowBuilds に載っていない依存があると install が失敗する。スクリプトを持つ依存は true か false で全部書く1つのリポジトリに package.json を持つフォルダが複数あるとき、「これらはひとまとまり」と pnpm に教える。
my-monorepo/
├── pnpm-workspace.yaml
├── apps/
│ ├── web/ package.json
│ └── admin/ package.json
└── packages/
└── ui/ package.json
# pnpm-workspace.yaml
packages:
- 'apps/*'
- 'packages/*'
これでできることは2つ。
pnpm install を1回実行すると、3つ全部の依存が入る。ロックファイルも1つ// apps/web/package.json
{
"dependencies": {
"@my-monorepo/ui": "workspace:*"
}
}
workspace:* は「レジストリから取らず、このまとまりの中の packages/ui を使う」という意味。packages: が無いと pnpm は packages/ui を知らず、レジストリへ探しに行って失敗する。
3つのパッケージがそれぞれ react を使うとき、各 package.json にバージョンを書くと、揃え続ける場所が3箇所になり、どこかがずれる。catalog: に1回だけ書き、各 package.json からはそれを参照する。
# pnpm-workspace.yaml(ここに1回だけ書く)
catalog:
react: 19.2.8
// 各 package.json(バージョンの代わりに)
{
"dependencies": {
"react": "catalog:"
}
}
react を上げるときは catalog: の1行を変えるだけで済む。アプリと共有部品で react の版がずれて壊れる、という事故を防げる。
パッケージが1つだけのプロジェクトには
packages:もcatalog:も要らない。それでも、次の「設定ファイル」としての役割のためにpnpm-workspace.yamlを置く。
pnpm の動作を決める設定の置き場所。
# pnpm-workspace.yaml
minimumReleaseAge: 10080 # 公開から7日たっていない版は入れない
engineStrict: true # Node のバージョンが合わなければ install を止める
overrides: # 依存の奥にあるパッケージの版を差し替える
lodash@<4.18.0: ^4.18.1
allowBuilds: # install 時のスクリプトを実行するか
esbuild: false
| 設定 | 何をするか | pnpm 10 までの置き場所の例 |
|---|---|---|
minimumReleaseAge |
公開から指定の分数(10080 分 = 7日)たっていない版を入れない | pnpm-workspace.yaml |
engineStrict |
Node のバージョンが engines と合わなければ install を止める |
.npmrc(engine-strict) |
overrides |
依存の奥にあるパッケージの版を差し替える | package.json の pnpm.overrides |
nodeLinker |
node_modules の並べ方(isolated / hoisted など) |
.npmrc(node-linker) |
allowBuilds |
install 時のスクリプトを実行するか | onlyBuiltDependencies など(廃止) |
nodeLinker で変わる node_modules の並べ方は npm・yarn・pnpm の node_modules の違い(巻き上げ・シンボリックリンク・PnP) を参照。
flowchart LR
PJ["package.json の pnpm フィールド<br/>(overrides など)"] -->|pnpm 11 から読まれない| WS
RC[".npmrc<br/>(engine-strict・node-linker など)"] -->|認証とレジストリ以外は<br/>pnpm 11 から読まれない| WS
WS["pnpm-workspace.yaml<br/>(設定はここに書く)"]
package.json の pnpm フィールドは、pnpm 11 から読まれない.npmrc は、認証・レジストリの設定だけ読まれる(プロキシなどのネットワーク設定は、npm からの移行のために .npmrc からも読める).npmrc で engine-strict のようにハイフン区切りだったキーは、pnpm-workspace.yaml では engineStrict のようにキャメルケースで書く設定を移さずに pnpm だけ上げると、エラーにならないまま設定が効かなくなる。たとえば
overridesが外れると、差し替えていた依存が古い版に戻る。
なお minimumReleaseAge は pnpm 11 から既定値が 1440(1日)になった。書かなくても、公開から1日たっていない版は入らない。
npm のパッケージは preinstall・install・postinstall のスクリプトを持てる。pnpm install の途中で、そのパッケージが用意したコマンドが手元や CI で走る。allowBuilds は、それをパッケージごとに許すかどうかの表。
allowBuilds:
ffmpeg-static: true # 実行する
esbuild: false # 実行しない
flowchart TD
A["install 中に、スクリプトを持つ<br/>依存パッケージが見つかった"] --> B{"allowBuilds に<br/>どう書いてあるか"}
B -->|true| C["スクリプトを実行する"]
B -->|false| D["実行せずに先へ進む"]
B -->|書いていない| E["pnpm 11 以降: install が失敗する<br/>pnpm 10: 警告を出して飛ばす"]
pnpm 11 から strictDepBuilds の既定値が true になった。これは「実行するかどうかを決めていないスクリプトを持つ依存があれば、install を 0 以外の終了コードで終える」という設定。
そのため、プロジェクトに入る依存(依存の依存も含む)のうち、install 時のスクリプトを持つものは 全部 allowBuilds に書く 必要がある。実行しないものも false と書く。
| pnpm | 依存パッケージのスクリプトの扱い |
|---|---|
| 9 まで | 全部実行する |
| 10 | 既定では実行しない。onlyBuiltDependencies に書いたものだけ実行。書いていないものは警告を出して飛ばす |
| 11 以降 | 書いていないものがあると install が失敗する。設定は allowBuilds の1つにまとまった(onlyBuiltDependencies・neverBuiltDependencies・ignoredBuiltDependencies などは廃止) |
10 から 12 へ一気に上げると、「設定の置き場所の移動」と「allowBuilds を全部書く」の両方がまとめて必要になる。
スクリプトが何をするかを見て決める。実際に調べた例:
| パッケージ | 値 | 理由 |
|---|---|---|
ffmpeg-static |
true |
スクリプトが ffmpeg 本体をダウンロードする。実行しないと使えない |
esbuild |
false |
実行ファイルは OS ごとの別パッケージで入る |
@parcel/watcher |
false |
通常は OS ごとの配布済みバイナリが使われる |
protobufjs |
false |
警告を出すだけで、ファイルを作らない |
pnpm 10 で警告つきで飛ばされたまま build やテストが通っていたものは、
falseと書いても動作は変わらない。「暗黙に飛ばされていたもの」を「実行しないと明示したもの」に変えるだけ。
allowBuilds に1行足すallowBuilds:
新しいパッケージ: false # 実行しなくても動くなら false、要るなら true
pnpm approve-builds でも書ける: 引数なしで実行すると対話形式で選べ、結果が allowBuilds に true / false で書き込まれる。pnpm approve-builds esbuild !core-js のように、名前を並べる(! を付けると拒否)書き方もあるdangerouslyAllowAllBuilds: true は使わない: 全部の依存のスクリプトを承認なしで実行する設定。今は安全でも、あとから入る依存や、乗っ取られたパッケージのスクリプトまで実行される'foo@git+ssh://git@example.com/org/foo.git': true のように、リポジトリの URL(またはコミットまで含めたパス)で書くpackage.json の pnpm フィールドや .npmrc に残した設定は、黙って無視される。上げる前に両方を見て、pnpm-workspace.yaml へ移す