monorepo-versioning

Monorepo Versioning & Internal Peer Dependencies

Internal peerDependencies must use workspace:^, never workspace:*

When one @solvapay/* package declares another as a peerDependency, the range must be workspace:^ (caret), not workspace:* (exact pin).

// ✅ correct
"peerDependencies": {
  "@solvapay/auth": "workspace:^"
}

// ❌ wrong — exact pin causes major-version cascades
"peerDependencies": {
  "@solvapay/auth": "workspace:*"
}

Why this matters (the cascade)

.changeset/config.json sets onlyUpdatePeerDependentsWhenOutOfRange: true, and a peer-dependency range change is a major bump by semver convention. workspace:* publishes as the exact current version (e.g. 1.0.8), so any bump to that peer — even a patch — puts the published range out of range and forces Changesets to bump every dependent to a new major.

Real example this rule exists to prevent: a patch to @solvapay/mcp-core and a minor to @solvapay/auth cascaded @solvapay/react, @solvapay/server, and @solvapay/react-supabase all to 2.0.0, with no breaking change anywhere.

workspace:^ publishes as ^<version>, so patch/minor peer bumps stay in range and do not cascade.

Note on pre-1.0 peers

For a 0.x peer, workspace:^ publishes as ^0.2.4, which only satisfies 0.2.x. A future 0.3.0 (minor) of that peer will cascade a major onto every dependent — this is correct semver, and pnpm's workspace: protocol cannot express a wider range.

While a peer is intentionally pre-1.0 (e.g. @solvapay/mcp-core, consumed by @solvapay/react and @solvapay/mcp), keep workspace:^ and ship that peer's changes as patch so they stay inside the dependents' ^0.2.x caret range and do not cascade. Pre-1.0 has no minor/patch compatibility contract, so an additive change is fine as a patch here.

Only take a minor/major on such a peer as a deliberate act — most notably a 1.0 stabilization, after which workspace:^ publishes ^1.0.0 and future minors stay in range. Expect (and document) a one-time major on the dependents when you cross 0.x → 1.0. Do not reach for an explicit published range to dodge a cascade that reflects a real break (e.g. narrowing >=0.2.7 <1 just to skip a bump a dependent genuinely needs): that hides a breaking change and drops the workspace: protocol.