Workspace
pnpm has built-in support for monorepositories (AKA multi-package repositories,multi-project repositories, or monolithic repositories). You can create aworkspace to unite multiple projects inside a single repository.
A workspace must have apnpm-workspace.yaml file in itsroot. A workspace also may have an.npmrc in its root.
If you are looking into monorepo management, you might also want to look intoBit.Bit uses pnpm under the hood but automates a lot of the things that are currently done manually in a traditional workspace managed by pnpm/npm/Yarn. There's an article aboutbit install that talks about it:Painless Monorepo Dependency Management with Bit.
Workspace protocol (workspace:)
Iflink-workspace-packages is set totrue, pnpm will link packages from the workspace if the available packagesmatch the declared ranges. For instance,foo@1.0.0 is linked intobar ifbar has"foo": "^1.0.0" in its dependencies andfoo@1.0.0 is in the workspace. However, ifbar has"foo": "2.0.0" in dependencies andfoo@2.0.0 is not in the workspace,foo@2.0.0 will be installed from the registry. This behavior introduces someuncertainty.
Luckily, pnpm supports theworkspace: protocol. Whenthis protocol is used, pnpm will refuse to resolve to anything other than alocal workspace package. So, if you set"foo": "workspace:2.0.0", this timeinstallation will fail because"foo@2.0.0" isn't present in the workspace.
This protocol is especially useful when thelink-workspace-packages option isset tofalse. In that case, pnpm will only link packages from the workspace iftheworkspace: protocol is used.
Referencing workspace packages through aliases
Let's say you have a package in the workspace namedfoo. Usually, you wouldreference it as"foo": "workspace:*".
If you want to use a different alias, the following syntax will work too:"bar": "workspace:foo@*".
Before publish, aliases are converted to regular aliased dependencies. The aboveexample will become:"bar": "npm:foo@1.0.0".
Referencing workspace packages through their relative path
In a workspace with 2 packages:
+ packages
+ foo
+ bar
bar may havefoo in its dependencies declared as"foo": "workspace:../foo". Before publishing, these specs are converted toregular version specs supported by all package managers.
Publishing workspace packages
When a workspace package is packed into an archive (whether it's throughpnpm pack or one of the publish commands likepnpm publish), we dynamicallyreplace anyworkspace: dependency by:
- The corresponding version in the target workspace (if you use
workspace:*,workspace:~, orworkspace:^) - The associated semver range (for any other range type)
So for example, if we havefoo,bar,qar,zoo in the workspace and they all are at version1.5.0, the following:
{
"dependencies":{
"foo":"workspace:*",
"bar":"workspace:~",
"qar":"workspace:^",
"zoo":"workspace:^1.5.0"
}
}
Will be transformed into:
{
"dependencies":{
"foo":"1.5.0",
"bar":"~1.5.0",
"qar":"^1.5.0",
"zoo":"^1.5.0"
}
}
This feature allows you to depend on your local workspace packages while stillbeing able to publish the resulting packages to the remote registry withoutneeding intermediary publish steps - your consumers will be able to use yourpublished workspaces as any other package, still benefitting from the guaranteessemver offers.
Release workflow
Versioning packages inside a workspace is a complex task and pnpm currently doesnot provide a built-in solution for it. However, there are 2 well tested toolsthat handle versioning and support pnpm:
For how to set up a repository using Rush, readthis page.
For using Changesets with pnpm, readthis guide.
Troubleshooting
pnpm cannot guarantee that scripts will be run in topological order if there are cycles between workspace dependencies. If pnpm detects cyclic dependencies during installation, it will produce a warning. If pnpm is able to find out which dependencies are causing the cycles, it will display them too.
If you see the messageThere are cyclic workspace dependencies, please inspect workspace dependencies declared independencies,optionalDependencies anddevDependencies.
Usage examples
Here are a few of the most popular open source projects that use the workspace feature of pnpm: