Version: Next

ワークスペース

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

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

ヒント

モノレポの管理を検討している場合は、Bit も検討することをお勧めします。 Bit は内部で pnpm を使用しますが、pnpm/npm/Yarn によって管理される従来のワークスペースで現在手動で行われている多くのことを自動化します。 bit install に関するこちらの記事に、それについて書かれています：Bit による苦痛なきモノレポジトリ依存関係管理 (英語)

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

デフォルトでは、使用可能なパッケージが宣言された範囲と一致する場合、 pnpm はワークスペースからパッケージをリンクします。例えば、bar が "foo": "^1.0.0" を依存関係に定義していて、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 はワークスペースからパッケージをリンクします。

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

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

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

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

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

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

+ packages
    + foo
    + bar

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

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

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

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

たとえば、ワークスペースに foo, bar, qar, zoo というパッケージがあり、全てバージョンが 1.5.0 であるときに、次のようなバージョン指定をしたとします:

{
    "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 をサポートした、よくテストされたツールです。

changesets
Rush.

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

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

Troubleshooting

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

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

使用例

pnpm のワークスペース機能を使用している特に有名なオープンソースプロジェクトのいくつかを以下に示します。

プロジェクト	移行日	移行コミット
Next.js	2022-05-29	`f7b81316aea4fc9962e5e54981a6d559004231aa`
Vite	2021-09-26	`3e1cce01d01493d33e50966d0d0fd39a86d229f9`
Nuxt	2022-10-17	`74a90c566c936164018c086030c7de65b26a5cb6`
Vue 3.0	2021-10-09	`61c5fbd3e35152f5f32e95bf04d3ee083414cecb`
Prisma	2021-09-21	`c4c83e788aa16d61bae7a6d00adc8a58b3789a06`
n8n	2022-11-09	`736777385c54d5b20174c9c1fda38bb31fbf14b4`
Slidev	2021-04-12	`d6783323eb1ab1fc612577eb63579c8f7bc99c3a`
Astro	2022-03-08	`240d88aefe66c7d73b9c713c5da42ae789c011ce`
Turborepo	2022-03-02	`fd171519ec02a69c9afafc1bc5d9d1b481fba721`
Element Plus	2021-09-23	`f9e192535ff74d1443f1d9e0c5394fad10428629`
Verdaccio	2021-09-21	`9dbf73e955fcb70b0a623c5ab89649b95146c744`
NextAuth.js	2022-05-03	`4f29d39521451e859dbdb83179756b372e3dd7aa`
VueUse	2021-09-25	`826351ba1d9c514e34426c85f3d69fb9875c7dd9`
SvelteKit	2021-09-26	`b164420ab26fa04fd0fbe0ac05431f36a89ef193`
Cycle.js	2021-09-21	`f2187ab6688368edb904b649bd371a658f6a8637`
Vercel	2023-01-12	`9c768b98b71cfc72e8638bf5172be88c39e8fa69`
Vitest	2021-12-13	`d6ff0ccb819716713f5eab5c046861f4d8e4f988`
Milkdown	2021-09-26	`4b2e1dd6125bc2198fd1b851c4f00eda70e9b913`
Nhost	2022-02-07	`10a1799a1fef2f558f737de3bb6cadda2b50e58f`
Logto	2021-07-29	`0b002e07850c8e6d09b35d22fab56d3e99d77043`
ByteMD	2021-02-18	`36ef25f1ea1cd0b08752df5f8c832302017bb7fb`
Rollup plugins	2021-09-21	`53fb18c0c2852598200c547a0b1d745d15b5b487`
icestark	2021-12-16	`4862326a8de53d02f617e7b1986774fd7540fccd`