Read pnpm Peer Dependency Warnings Before Adding `--force`

A warning is a relationship, not just noise

Peer dependencies describe a package that expects the consuming project to provide another package, commonly a framework or plugin API. pnpm's strict layout makes some mismatches more visible than a flat dependency tree. A warning can be harmless in a narrow case, but it can also indicate a plugin built for another major version.

Read the warning's package path and expected range. Then inspect the actual host version with pnpm why react or the relevant framework package. Check whether the plugin documents support for that major and whether the warning is introduced by a workspace package with stale peer metadata.

Fix the relationship instead of muting it

If the peer range is incorrect but the code supports the installed host, upgrade to a package release that corrects the metadata or patch the package through a maintained process. If the versions truly conflict, align the host and plugin or select a compatible plugin version.

--force and --strict-peer-dependencies=false can be diagnostic experiments, but leaving them as a universal install setting can hide a runtime incompatibility. If an exception is needed, scope it to the known package and document why it is safe. Run the tests that exercise the integration, not only a clean install.

Keep peer ranges honest in your own library. Test the minimum and current supported host versions in CI when the package is intended for reuse. A useful peer warning narrows the investigation; the goal is to understand the API contract, not achieve a warning-free terminal at any cost.

Determine whether the mismatch is executable risk

Look at the peer range, installed host version, and integration code that consumes the host API. A mismatch between adjacent patch releases may be metadata that is too narrow; a mismatch across major versions can indicate a real API break. Check the package's support matrix and release notes, then run the feature that uses the plugin. A warning-free installation is not a compatibility test, and a warning alone does not prove the application is broken.

In a workspace, inspect whether the warning comes from a local package whose peer declaration has not been updated. The implementation may support a framework version that its peerDependencies do not list. Fix the metadata only after testing the API, because publishing an expanded range makes a promise to future consumers. For an application, decide whether to align the host, upgrade the plugin, or pin a compatible combination. Record the chosen versions so the next dependency update does not recreate the same uncertainty.

Use exceptions as temporary experiments

Flags such as force or relaxed peer enforcement can answer a narrow question: does resolution proceed far enough to reproduce a runtime issue? Run the experiment in a throwaway branch or local command and keep normal repository configuration unchanged. If the feature works, add tests and determine why the peer contract differed before deciding whether to keep an exception. Do not set a global relaxed flag just to make all contributors' installs quiet.

For libraries, define the peer range based on tested host versions and use a CI matrix for the minimum and current supported versions where practical. For applications, an explicit package combination is often easier to maintain than an enormous range of host versions. Review peer warnings after upgrades, especially for framework plugins, adapters, and testing libraries. The right resolution is a documented compatibility decision backed by behavior, not a terminal with fewer yellow lines.

When a peer warning is accepted, add a comment or issue link near the configuration that suppresses it, including the package version and reason. Recheck after upgrading either side of the relationship. Peer contracts can change independently of runtime code, and a temporary mismatch can become a real incompatibility later. Prefer a narrow, package-specific exception over changing the team's default install behavior for every dependency.

The accepted exception should have an integration test that exercises the host and plugin together. If the warning comes from a local package, update its peer metadata only after testing the supported host range; publishing an expanded range makes a promise to consumers. Keep force flags out of global configuration and review them during dependency upgrades.