YASD-TECH
YASD TECH
# JavaScript

pnpm-workspace.yaml の役割と allowBuilds(ワークスペース定義・設定ファイル・install 時スクリプトの許可)

投稿日:2026/11/18

更新日:2026/11/18

ttitleImage

pnpm-workspace.yaml の役割と allowBuilds(ワークスペース定義・設定ファイル・install 時スクリプトの許可)

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 の動作を決める設定を書く(設定ファイル)
  • pnpm 11 から、package.json の pnpm フィールドは読まれず、.npmrc は認証とレジストリの設定しか読まれない。設定は pnpm-workspace.yaml に書く。パッケージが1つだけのプロジェクトでも置く
  • allowBuilds は、依存パッケージが install 時に動かすスクリプトを パッケージごとに実行するか・しないか 決める表
  • pnpm 11 から、スクリプトを持つのに allowBuilds に載っていない依存があると install が失敗する。スクリプトを持つ依存は true か false で全部書く

役割1: ワークスペース(モノレポ)の定義

1つのリポジトリに package.json を持つフォルダが複数あるとき、「これらはひとまとまり」と pnpm に教える。

text
my-monorepo/
├── pnpm-workspace.yaml
├── apps/
│   ├── web/        package.json
│   └── admin/      package.json
└── packages/
    └── ui/         package.json
yaml
# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

これでできることは2つ。

  • pnpm install を1回実行すると、3つ全部の依存が入る。ロックファイルも1つ
  • 隣のフォルダを、npm のパッケージのように使える
json
// apps/web/package.json
{
  "dependencies": {
    "@my-monorepo/ui": "workspace:*"
  }
}

workspace:* は「レジストリから取らず、このまとまりの中の packages/ui を使う」という意味。packages: が無いと pnpm は packages/ui を知らず、レジストリへ探しに行って失敗する。

catalog: バージョンを1箇所に書く

3つのパッケージがそれぞれ react を使うとき、各 package.json にバージョンを書くと、揃え続ける場所が3箇所になり、どこかがずれる。catalog: に1回だけ書き、各 package.json からはそれを参照する。

yaml
# pnpm-workspace.yaml(ここに1回だけ書く)
catalog:
  react: 19.2.8
json
// 各 package.json(バージョンの代わりに)
{
  "dependencies": {
    "react": "catalog:"
  }
}

react を上げるときは catalog: の1行を変えるだけで済む。アプリと共有部品で react の版がずれて壊れる、という事故を防げる。

パッケージが1つだけのプロジェクトには packages: も catalog: も要らない。それでも、次の「設定ファイル」としての役割のために pnpm-workspace.yaml を置く。


役割2: pnpm の設定ファイル

pnpm の動作を決める設定の置き場所。

yaml
# 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) を参照。

pnpm 11 から置き場所が1箇所になった

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日たっていない版は入らない。


allowBuilds

npm のパッケージは preinstall・install・postinstall のスクリプトを持てる。pnpm install の途中で、そのパッケージが用意したコマンドが手元や CI で走る。allowBuilds は、それをパッケージごとに許すかどうかの表。

yaml
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 から)

pnpm 11 から strictDepBuilds の既定値が true になった。これは「実行するかどうかを決めていないスクリプトを持つ依存があれば、install を 0 以外の終了コードで終える」という設定。

そのため、プロジェクトに入る依存(依存の依存も含む)のうち、install 時のスクリプトを持つものは 全部 allowBuilds に書く 必要がある。実行しないものも false と書く。

段階的に厳しくなってきた

pnpm 依存パッケージのスクリプトの扱い
9 まで 全部実行する
10 既定では実行しない。onlyBuiltDependencies に書いたものだけ実行。書いていないものは警告を出して飛ばす
11 以降 書いていないものがあると install が失敗する。設定は allowBuilds の1つにまとまった(onlyBuiltDependencies・neverBuiltDependencies・ignoredBuiltDependencies などは廃止)

10 から 12 へ一気に上げると、「設定の置き場所の移動」と「allowBuilds を全部書く」の両方がまとめて必要になる。

true にするか false にするかの決め方

スクリプトが何をするかを見て決める。実際に調べた例:

パッケージ 値 理由
ffmpeg-static true スクリプトが ffmpeg 本体をダウンロードする。実行しないと使えない
esbuild false 実行ファイルは OS ごとの別パッケージで入る
@parcel/watcher false 通常は OS ごとの配布済みバイナリが使われる
protobufjs false 警告を出すだけで、ファイルを作らない

pnpm 10 で警告つきで飛ばされたまま build やテストが通っていたものは、false と書いても動作は変わらない。「暗黙に飛ばされていたもの」を「実行しないと明示したもの」に変えるだけ。


ハマりどころ

  • 依存の更新で install が止まる: 更新で、スクリプトを持つパッケージが新しく入ると install が失敗する。依存の自動更新の PR でも同じ。スクリプトの中身を見て、allowBuilds に1行足す
yaml
allowBuilds:
  新しいパッケージ: false   # 実行しなくても動くなら false、要るなら true
  • pnpm approve-builds でも書ける: 引数なしで実行すると対話形式で選べ、結果が allowBuilds に true / false で書き込まれる。pnpm approve-builds esbuild !core-js のように、名前を並べる(! を付けると拒否)書き方もある
  • dangerouslyAllowAllBuilds: true は使わない: 全部の依存のスクリプトを承認なしで実行する設定。今は安全でも、あとから入る依存や、乗っ取られたパッケージのスクリプトまで実行される
  • git から入れる依存は名前だけでは許可されない: 'foo@git+ssh://git@example.com/org/foo.git': true のように、リポジトリの URL(またはコミットまで含めたパス)で書く
  • 設定の移し忘れはエラーにならない: package.json の pnpm フィールドや .npmrc に残した設定は、黙って無視される。上げる前に両方を見て、pnpm-workspace.yaml へ移す

参考

Index

  • pnpm-workspace.yaml の役割と allowBuilds(ワークスペース定義・設定ファイル・install 時スクリプトの許可)
  • 結論
  • 役割1: ワークスペース(モノレポ)の定義
  • catalog: バージョンを1箇所に書く
  • 役割2: pnpm の設定ファイル
  • pnpm 11 から置き場所が1箇所になった
  • allowBuilds
  • スクリプトを持つ依存は全部書く(pnpm 11 から)
  • 段階的に厳しくなってきた
  • true にするか false にするかの決め方
  • ハマりどころ
  • 参考