check-peer-dependencies

Checks peer dependencies of the current NodeJS package. Offers solutions for any that are unmet.

This utility will recursively find all peerDependencies in your project's dependencies list. It checks if you have installed a package that meets the required peer dependency versions. If any peer dependencies are unmet, it will search for a compatible version to install.

Note: you must run npm install or yarn first in order to install all normal dependencies.

usage:

npx check-peer-dependencies [--yarn|--npm] [--install] [--help]

Options:

  -h, --help                       Print usage information             [boolean]
      --version                    Show version number                 [boolean]
      --yarn                       Force yarn package manager          [boolean]
      --npm                        Force npm package manager           [boolean]
      --orderBy                    Order the output by depender or dependee
                         [choices: "depender", "dependee"] [default: "dependee"]
      --debug                      Print debugging information
                                                      [boolean] [default: false]
      --verbose                    Prints every peer dependency, even those that
                                   are met            [boolean] [default: false]
      --ignore                     package name to ignore (may specify multiple)
                                                           [array] [default: []]
      --runOnlyOnRootDependencies  Run tool only on package root dependencies
                                                      [boolean] [default: false]
      --findSolutions              Search for solutions and print package
                                   installation commands
                                                      [boolean] [default: false]
      --install                    Install missing or incorrect peerDependencies
                                                      [boolean] [default: false]

Installing peerDependencies as devDependencies

If a package has a peerDependency that should be installed as a devDependency by, it can list the package name in "peerDevDependencies".
This is not a standard and is only understood by this check-peer-dependencies.

{
  "name": "somepackage",
  "peerDependencies": {
    "react": "16.x",
    "react-dom": "16.x",
    "typescript": "~3.8.0",
    "eslint": "*"
  },
  "peerDevDependencies": ["typescript", "eslint"]
}

Development

Use Node.js 22.22.1 or newer and npm 11 for development. Commit dependency changes with package-lock.json, the repository’s only lockfile.

npm ci
npm run build
npm run format
npm run format:check
npm test

Oxfmt formats the TypeScript sources and JavaScript tests. The pre-commit hook formats staged files using lint-staged.

See the test guide to run one downstream scenario or add a fixture of your own.

Example outputs:

No problems

~/projects/uirouter/sample-app-react master
❯ npx check-peer-dependencies
✅  All peer dependencies are met

Missing peer dependency, solution found

~/projects/uirouter/angular-hybrid master ⇣
❯ npx check-peer-dependencies
❌  @uirouter/[email protected] requires @angular/router ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0 (@angular/router is not installed)

Searching for solutions:
yarn add @angular/[email protected]

Incorrect peer dependencies, some solutions found

❯ npx check-peer-dependencies
❌  @uirouter/[email protected] requires @angular/common ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0 (9.0.0-next.9 is installed)
❌  @uirouter/[email protected] requires @angular/core ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0 (9.0.0-next.9 is installed)
❌  @uirouter/[email protected] requires @angular/router ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0 (9.0.0-next.9 is installed)

Searching for solutions:
❌  Unable to find a version of @angular/common that satisfies the following peerDependencies: 9.0.0-next.9 and ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0
❌  Unable to find a version of @angular/core that satisfies the following peerDependencies: 9.0.0-next.9 and ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0

yarn upgrade @angular/[email protected]

Package manager execution

Registry queries and automatic installation pass arguments directly to npm/yarn without a shell. Peer names must be registry package names (including scoped names); paths, URLs, package specs, unscoped archive-like names and options are rejected. Version ranges are used only for semver matching, and installation uses the validated version returned by the registry. Printed installation commands are quoted for POSIX shells; they are never used to execute automatic installation.

Control characters in checker diagnostics are displayed as visible escapes, so package metadata cannot issue terminal commands or insert misleading lines into a report.

On Windows, standard npm, Yarn Classic and Corepack .cmd installations on PATH are supported by launching their JavaScript entry points with Node, including project-local node_modules/.bin shims. Custom shims without a recognized entry point fail rather than falling back to shell execution. Printed POSIX commands are not intended for PowerShell or cmd.exe. Installing packages still runs the package manager's normal lifecycle scripts.