pnpm-workspace

pnpm ワークスペース

概要

pnpm ワークスペースは、pnpm-workspace.yaml による組み込みのモノレポサポート、ローカルパッケージのリンクに使う workspace: プロトコル、特定のパッケージ間でコマンドを実行できる強力なフィルタリング機能を提供します。カタログを使うと、ワークスペース内のすべてのパッケージで依存関係のバージョンを統一できます。

使用する場面： 複数パッケージのリポジトリ、利用側アプリと共有ライブラリがある場合、パッケージ間で依存関係を一貫して管理する場合、パッケージの一部を対象にコマンドを実行する場合。

使用しない場面： 単一パッケージのプロジェクト、すでに npm/yarn ワークスペースを使用しているプロジェクト（移行が必要）、パッケージごとにバージョン範囲が変動する依存関係が必要なプロジェクト。

クイックリファレンス

パターン	API / 設定	主なポイント
ワークスペースを定義する	pnpm-workspace.yaml の packages グロブ	package.json を含むディレクトリに一致します
ローカルパッケージをリンクする	"dep": "workspace:*"	常にローカルのワークスペースパッケージを解決します
バージョン範囲を指定してリンクする	"dep": "workspace:^1.0.0"	ローカルのバージョンが範囲を満たさない場合、インストールに失敗します
デフォルトカタログ	pnpm-workspace.yaml の catalog: キー	依存関係のバージョンを管理する唯一の情報源
名前付きカタログ	名前付きグループを指定する catalogs: キー	複数のバージョンセット（例：react18、react17）
パッケージでカタログを使用する	"dep": "catalog:" または "dep": "catalog:name"	pnpm publish 時に実際のバージョンへ解決されます
名前でフィルタリングする	--filter <name> または -F <name>	完全一致またはグロブパターン（@scope/*）
依存関係を含めてフィルタリングする	--filter "foo..."	パッケージとそのすべての依存関係
依存元を含めてフィルタリングする	--filter "...foo"	パッケージと、それに依存するすべてのパッケージ
ディレクトリでフィルタリングする	--filter "./packages/app"	ディレクトリパス配下のすべてのパッケージ
Git の変更でフィルタリングする	--filter "[origin/main]"	コミットまたはブランチ以降に変更されたパッケージ
フィルターから除外する	--filter "!foo"	一致するパッケージを選択対象から除外します
パッケージでスクリプトを実行する	pnpm --filter <pkg> <script>	一致したパッケージでのみスクリプトを実行します
再帰的に実行する	pnpm -r run <script>	ワークスペース内のすべてのパッケージでスクリプトを実行します
すべてをインストールする	pnpm install	ワークスペース全体で単一のロックファイルを使用します
ワークスペースパッケージを公開する	pnpm publish	workspace: と catalog: を実際のバージョンに置き換えます
ワークスペースの依存関係を注入する	.npmrc の inject-workspace-packages=true	シンボリックリンクではなくハードリンクを使用します。デプロイに必要です
スクリプトのセキュリティ（v10+）	package.json の allowBuilds	ライフサイクルスクリプトはデフォルトでブロックされます。依存関係ごとに許可します

よくある間違い

間違い	正しい方法
workspace:* を使用したまま公開する	pnpm は公開時に workspace:* を実際のバージョンに自動で置き換えます
packages: にディレクトリを記載し忘れる	すべてのパッケージディレクトリは、pnpm-workspace.yaml の glob に一致する必要があります
ワークスペースのパッケージで npm install を使用する	必ずワークスペースのルートから pnpm install を使用します
パッケージ間でバージョンを重複してハードコードする	catalog: を使用してバージョン定義を一元管理します
サブパッケージ内で pnpm install を実行する	ワークスペースのルートから実行し、対象パッケージの指定には --filter を使用します
--filter がディレクトリ名に一致すると想定する	--filter はディレクトリ名ではなく、package.json の name フィールドに一致します
zsh で除外フィルターの ! をエスケープしない	\! を使用するか、フィルターを引用符で囲みます：--filter="!foo"
ワークスペース外の依存関係に workspace: を使用する	workspace: プロトコルは、ワークスペースに定義されたパッケージでのみ機能します
pnpm 10 へのアップグレード後にライフサイクルスクリプトが失敗する	pnpm 10 ではスクリプトがデフォルトでブロックされます。設定の allowBuilds に依存関係を追加します
inject-workspace-packages を設定せずに pnpm deploy を使用する	.npmrc で inject-workspace-packages=true を設定します（pnpm 10 では必須です）

委任

• ワークスペースの足場作り：既存のパッケージ構成を調査するには、Explore エージェントを使用します
• 依存関係の監査：パッケージ間のバージョンの一貫性を確認するには、Task エージェントを使用します

turborepo スキルが利用可能な場合は、ビルドのオーケストレーション、タスクのキャッシュ、CI の最適化を委任します。 changesets スキルが利用可能な場合は、バージョン管理、変更履歴の生成、npm への公開を委任します。

参考資料

• ワークスペースのセットアップ、ワークスペースプロトコル、カタログ
• 対象を絞ったコマンドのためのパッケージのフィルタリング
• ワークスペースパッケージ間で共有する設定
• モノレポの統合：pnpm + Turborepo + Changesets パイプライン