Setting a package's peerDependencies to a range of another package in the monorepo with workspace

[TheSonOfThomp]

Hey all! I noticed the documentation doesn't mention (or it's hard to find) how to correctly set peer dependency ranges for packages within the same monorepo. Below is what my team has come up with.
If we've done something incorrectly, or there's a better way to do this, let us know!

The problem

We have a monorepo React UI library with a structure like below:

packages/
  | context-provider/
  | component-a
  | component-b
  | ...

To ensure consumers of our components always have a single version of the provider installed, we set each component to have a peer dependency on the context-provider.

// package.json
{
  "name": "@scope/component-a",
  "peerDependencies": {
    "@scope/context-provider": "workspace:^"
  }
}

Previously we had this version set to workspace:^ in order to always use the local version while testing. However, we realized that this would be bumped with every new release of the provider, causing churn and possibly incorrect peer dependencies (e.g. if the peer dependency had a backwards-compatible minor/patch release, the component package would bump the peer dependency version, even though any version of the latest major (i.e. ^X.0.0) would work.

Step 1. Fixed major workspace version

We were able to resolve this first issue by setting the peer dependency version to the following (where X is the latest major version of the provider).

  "name": "@scope/component-a",
  "peerDependencies": {
    "@scope/context-provider": "workspace:^X.0.0"
  }

This way when we make changes to the provider, those are reflected locally, but the published version of the component package still depends on any version of the latest major.

But what if the context provider is backwards compatible (in most cases) one or more major versions?

Step 2. Ranged major workspace versions

For example, the latest version of our context provider is v5.0.0, but the vast majority of components work all the way back to v3.2.0. So if a consumer is only using these components, and don't want to update the provider from v3.2.0, they don't need to.

After some experimentation (and bad releases) we were finally able to determine how to define a range of peer dependencies, that includes the latest local workspace version.

// package.json
{
  "name": "@scope/component-a",
  "peerDependencies": {
    "@scope/context-provider": "workspace:^5.0.0 || ^4.0.0 || ^3.2.0"
  }
}

Some notes and caviats we discovered:

• pnpm only converts the first reference of workspace when packing/publishing. i.e. something like workspace:^5.0.0 || workspace:^4.0.0 will not work
• pnpm install seems to resolve the _first_version in a range locally. So specifying the above in reverse order (i.e. "^3.2.0 || ^4.0.0 || workspace:^5.0.0") will result in v3.2.0 being downloaded and installed locally, instead of the latest workspace version
• This also means that other range specifiers won't work
  • e.g. ">=3.2.0 <=workspace:^5.0.0" will install v3.2.0, and so will "3.2.0 - workspace:^5.0.0"
  • I'm not 100% sure why the inverse range doesn't work, ("<=workspace:^5.0.0 >=3.2.0 ") but IMO the explicit range above is more readable

How did I validate this?

There are 2 conditions that needed to be met:

1. The peer dependency version resolved by pnpm locally needed to link to the local package, and
2. The peer dependency specifier in the packed & published version needed to be valid and allow resolution to any of the above versions

1. Validating locally installed packages

To test this I set the specifier in the package.json, ran pnpm install (with autoInstallPeers: true), and verified the installed version in the pnpm-lock.yml was version: link:../context-provider

packages/component-a:
    dependencies:
      '@scope/context-provider':
        specifier: workspace:^5.0.0 || ^4.0.0 || ^3.2.0
        version: link:../context-provider

2. Validating the published package.json

To test this I ran pnpm pack from the component directory, unzipped the package, and verified that it created a package.json with correctly resolved peer dependencies

// component-a/package/package.json
{
  "name": "@scope/component-a",
  "peerDependencies": {
    "@scope/context-provider": "^5.0.0 || ^4.0.0 || ^3.2.0"
  }
}