Version: 6.x

ワークスペース

pnpm には、モノリポジトリ（別名、マルチプロジェクトリポジトリ、またはモノリシックリポジトリ）のサポートが組み込まれています。ワークスペースを作成して、単一のリポジトリ内で複数のプロジェクトを統合できます。

ワークスペースを作成するには、ルートに pnpm-workspace.yaml を作成します。また、ワークスペースではルートに .npmrc を置くこともできます。

ワークスペースプロトコル (workspace:)

追加されたバージョン：v3.7.0

デフォルトでは、使用可能なパッケージが宣言された範囲と一致する場合、 pnpm はワークスペースからパッケージをリンクします。たとえば、 foo@1.0.0 は、 "foo": "^1.0.0" を依存として定義している bar プロジェクトにリンクされます。ただし、 bar が依存として "foo": "2.0.0" を定義しても、foo@2.0.0 がワークスペース側になければ、foo@2.0.0 はレジストリからインストールされます。この動作はいくつかの不確実性をもたらします。

幸い、pnpmは workspace: プロトコルをサポートしています。このプロトコルが使用されている場合、 pnpm はローカルにあるワークスペースパッケージ以外のものに解決されることを禁止します。そのため、 "foo": "workspace:2.0.0"を設定すると、今回は "foo@2.0.0" がワークスペースに存在しないため、インストールに失敗します。

このプロトコルは、 link-workspace-packages オプションが false に設定されている場合に特に便利です。この場合、 workspace: プロトコルが使用されている場合にのみ、pnpm はワークスペースからパッケージをリンクします。

エイリアスを介したワークスペースパッケージの参照

追加されたバージョン：v5.12.0

たとえば、 foo という名前のパッケージがワークスペースにあるとします。通常、 "foo": "workspace:*" として参照します。

別のエイリアスを使用する場合は、次の構文も使用できます: "bar": "workspace:foo@*".

公開する前に、エイリアスは通常のエイリアスされた依存関係に変換されます。上記の例は "bar": "npm:foo@1.0.0" になります。

相対パスでワークスペースのパッケージを参照する

追加されたバージョン：v5.12.0

ワークスペースに 2 つのパッケージがあるとします:

+ packages
    + foo
    + bar

bar は foo を依存として "foo": "workspace:../foo" と宣言することができます。公開する前に、これらのバージョン指定はすべてのパッケージマネージャーがサポートしている通常のバージョン指定に変換されます。

ワークスペースのパッケージの公開

ワークスペースのパッケージが (pnpm pack や pnpm publish などのコマンドを使用して) アーカイブファイルにパックされる際に、 workspace: プロトコルで書かれた依存関係を次のように変換します。

そのワークスペースにある対応するバージョン (workspace:*、workspace:~、workspace:^ のいずれかのバージョン指定方法を使っている場合)
対応する semver の範囲指定 (その他の範囲指定を使っている場合)

So for example, if we have foo, bar, qar, zoo in the workspace and they all are at version 1.5.0, the following:

{
    "dependencies": {
        "foo": "workspace:*",
        "bar": "workspace:~",
        "qar": "workspace:^",
        "zoo": "workspace:^1.5.0"
    }
}

これは以下のように変換されます。

{
    "dependencies": {
        "foo": "1.5.0",
        "bar": "~1.5.0",
        "qar": "^1.5.0",
        "zoo": "^1.5.0"
    }
}

この機能により、ローカルにあるワークスペースのパッケージに依存する指定を使用しながら、最終的にパッケージをレジストリに公開する際に追加の変換ステップを挟む必要がなくなります。あなたのパッケージの使用者は、公開されたパッケージを他のパッケージとなんら変わらないように使うことができ、semver の指定による保証を受け続けることができます。

リリースワークフロー

ワークスペース内のパッケージのバージョニングは複雑なタスクであり、現時点では pnpm は組み込みの解決方法を提供していません。しかし、次の 2 つは、バージョニングを扱う pnpm をサポートした、よくテストされたツールです。

Rush を使用してレポジトリをセットアップする方法については、こちらのページ (英語) を参照してください。

Changeset を pnpm と組み合わせて使用する方法については、こちらのガイドを参照してください。

Options

link-workspace-packages

Added in: v2.14.0

デフォルト: true
タイプ: true, false, deep

このオプションを有効にすると、ローカルで利用可能なパッケージはレジストリからダウンロードせずに node_modules へとリンクされます。これはモノレポで非常に役立ちます。間接的な依存関係にもローカルのパッケージをリンクする場合は、deep を指定することができます。 (v5以降)

それ以外の場合には、依存はレジストリからダウンロードされます。ただし、ワークスペースのパッケージは workspace: プロトコルを範囲指定することでリンクすることができます。

prefer-workspace-packages

追加されたバージョン：v5.13.0

デフォルト: false
タイプ: Boolean

このオプションを有効にすると、レジストリに新しいバージョンのパッケージがある場合でも、ワークスペース内のローカルにあるパッケージが優先されます。

この設定は、ワークスペースのオプションで save-workspace-protocol が使用されていない場合にのみ役立ちます。

shared-workspace-lockfile

追加されたバージョン：v2.17.0 で shared-workspace-shrinkwrap として追加

デフォルト: true
タイプ: Boolean

このオプションが有効になっている場合、pnpm はワークスペースのルートの pnpm-lock.yaml のみを作成します。これにより、すべてのワークスペースの依存がワークスペースのルートの node_modules この一箇所に集められます。(そして各パッケージの node_modules ディレクトリへとシンボリックリンクが作成されます。)

このオプションの利点:

各依存の一箇所への設置
より高速なモノレポでのインストール
一箇所にすべて記述され、より少ないコードレビュー時の変更

note

たとえルートの node_modules にすべての依存がハードリンクされていても、各ワークスペースパッケージはその package.json に定義された依存にしかアクセスできません。これにより、 pnpm の厳密性は保持されます。これは前述のシンボリックリンクによるものです。

save-workspace-protocol

デフォルト: true
タイプ: Boolean

このオプションを有効にすると、新しい依存はワークスペースに存在している場合にのみ追加されます。

リポジトリで使用しているツールがワークスペースプロトコルを解釈できない場合にこのオプションを false にします。(また、将来的にワークスペースプロトコルに対応できるように、そのツールに PR を送ることも理想的です。)

トラブルシューティング

pnpm は、ワークスペース依存関係間に循環がある場合、スクリプトがトポロジカル順序で実行されることを保証しません。 pnpm がインストール時に循環する依存関係を検出すると、警告が表示されます。どの依存パッケージが循環の原因となっているかわかれば、pnpm はそれを表示します。

There are cyclic workspace dependencies といったメッセージが表示された場合は、dependencies, optionalDependencies, devDependencies に定義された依存関係を調査してください。

Usage examples

Here are a few open source projects that use the workspace feature of pnpm:

icestark (as of 12/16/2021, commit 4862326a8de53d02f617e7b1986774fd7540fccd)
Vue 3.0 (as of 10/9/2021, commit 61c5fbd3e35152f5f32e95bf04d3ee083414cecb)
Vite (as of 9/26/2021, commit 3e1cce01d01493d33e50966d0d0fd39a86d229f9)
Cycle.js (as of 9/21/2021, commit f2187ab6688368edb904b649bd371a658f6a8637)
Prisma (as of 9/21/2021, commit c4c83e788aa16d61bae7a6d00adc8a58b3789a06)
Verdaccio (as of 9/21/2021, commit 9dbf73e955fcb70b0a623c5ab89649b95146c744)
Rollup plugins (as of 9/21/2021, commit 53fb18c0c2852598200c547a0b1d745d15b5b487)
Milkdown (as of 9/26/2021, commit 4b2e1dd6125bc2198fd1b851c4f00eda70e9b913)
ByteMD (as of 2/18/2021, commit 36ef25f1ea1cd0b08752df5f8c832302017bb7fb)
VueUse (as of 9/25/2021, commit 826351ba1d9c514e34426c85f3d69fb9875c7dd9)
Slidev (as of 4/12/2021, commit d6783323eb1ab1fc612577eb63579c8f7bc99c3a)
SvelteKit (as of 9/26/2021, commit b164420ab26fa04fd0fbe0ac05431f36a89ef193)
Telecraft (as of 9/26/2021, commit 73a9c48c9d4f160d758b8881f404cc52c20a7454)
GiraphQL (as of 8/4/2021, commit 3dd3ff148da382d6f406f20626a9a5c25707c0c8)
Tailchat (as of 12/27/2021, commit 298af71aa0619e0a8fa8717777afe2fb32739db4)

ワークスペースプロトコル (workspace:)​

エイリアスを介したワークスペースパッケージの参照​

相対パスでワークスペースのパッケージを参照する​

ワークスペースのパッケージの公開​

リリースワークフロー​

Options​

link-workspace-packages​

prefer-workspace-packages​

shared-workspace-lockfile​