pnpm overrides cannot force a peerDependency — use a .pnpmfile.cjs readPackage hook to remap it

Situation: a package requires @solana/web3.js@^2 as a peerDependency, but your app cannot upgrade its own @solana/web3.js because other dependencies still need v1. The v2 build is already installed under an alias (for example web3js-experimental). You want the new package to resolve its peer against that alias.

pnpm.overrides does not do this. Neither "$web3js-experimental", "^2.0.0", nor "npm:@solana/web3.js@2.0.0" on the right-hand side of an override entry satisfies a peerDependency — overrides rewrite dependency resolution, not peer requirements.

What works is a readPackage hook, which lets you rewrite a package's manifest at install time: move the peer requirement into a real dependency and delete the peer entry, so pnpm installs a concrete copy instead of complaining.

.pnpmfile.cjs at the workspace root:

const remapPeerDependencies = [
  { package: '@solana-program/compute-budget', packageVersion: '0.6.1',
    peerDependency: '@solana/web3.js', newVersion: '2.0.0' },
];

function overridesPeerDependencies(pkg) {
  for (const dep of remapPeerDependencies) {
    if (pkg.name === dep.package && pkg.version.startsWith(dep.packageVersion)
        && pkg.peerDependencies?.[dep.peerDependency]) {
      pkg.dependencies[dep.peerDependency] = dep.newVersion;
      delete pkg.peerDependencies[dep.peerDependency];
    }
  }
}

module.exports = { hooks: { readPackage(pkg) { overridesPeerDependencies(pkg); return pkg; } } };

Then reinstall. Match on version prefix as shown, so a future release of the dependency does not silently keep the rewrite.

The consequence to accept: you now have two copies of the library in the graph, which is fine for @solana/web3.js v1 and v2 (different module identities, no shared global state) but is not safe in general. This is a pnpm mechanism, independent of Solana; the same hook solves any unsatisfiable peer.

Source: adapted from a Stack Exchange answer by ngundotra (question by ngundotra), https://solana.stackexchange.com/questions/17553/how-do-i-use-npm-packages-that-require-the-new-web3-js — CC BY-SA 4.0