check-package-dependencies

Check package dependencies for duplicates, peer dependencies satisfaction and more early

Install

npm install --save-dev check-package-dependencies
Copy

What is it for ?

Based on my experience, I often saw issues with duplicate dependencies like two versions of babel, or two versions a react library that cannot share a context, peer dependencies not respected. I wrote specific script inside each repository for a long time, but they tend to be hard to maintain, hard to read, and not generic enough.

I you have any idea, or found bug, please open an issue.

Try it with cli

Use npx to check the package.json of the current directory, and the package.json of every workspace member when it declares workspaces:

npx check-package-dependencies
Copy

The cli runs the recommended config through eslint, which it needs installed (npm install --save-dev eslint). It ignores the eslint configuration of the project, so no setup is required, and takes an optional directory:

npx check-package-dependencies packages/app
Copy

Option	Description
--fix	apply the fixes the rules provide
--quiet	report errors only, hiding warnings
--format <name>	eslint formatter to use (default: stylish)
--potential-directories <level>	how a workspaces glob matching a directory that holds no package.json is reported: off, warn (default) or error
-h, --help	show the usage

To enable other rules, to configure their options, or to lint package.json alongside the rest of the codebase, use the eslint plugin instead of the cli.

ESLint plugin

The plugin lints package.json files with a dedicated ESLint language, so errors are reported inline, with fixes and suggestions when possible.

// eslint.config.js
import checkPackageDependenciesPlugin from "check-package-dependencies/eslint-plugin";

export default [checkPackageDependenciesPlugin.configs.recommended];
Copy

Available configs:

Config	Emoji	Description
base		Only registers the package-json language and the plugin. No rule enabled.
recommended	✅	Recommended rules. A library is not checked like a package that is not published: this is driven by the library setting, not by config.

To enable a rule that is not part of a config, or to change its options, add it to your config:

export default [
  checkPackageDependenciesPlugin.configs.recommended,
  {
    files: ["**/package.json"],
    rules: {
      "check-package-dependencies/satisfies-versions": [
        "error",
        { devDependencies: { eslint: "^10.0.0" } },
      ],
    },
  },
];
Copy

Every rule declares the package-json language it supports through meta.languages, so ESLint reports a rule-unsupported-language error instead of silently doing nothing when a rule is enabled on a config entry that lints something else. Registering the plugin under another name keeps working, the plugin declaring check-package-dependencies as its meta.namespace:

export default [
  {
    files: ["package.json"],
    plugins: { pkg: checkPackageDependenciesPlugin },
    language: "pkg/package-json",
    rules: { "pkg/require-pinned-versions": "error" },
    // the settings key is the plugin namespace, whatever name the plugin is registered under
    settings: { "check-package-dependencies": { library: false } },
  },
];
Copy

Settings

Setting	Default	Description
library	"auto"	Whether a package is published and consumed by other packages. A library keeps ranges in dependencies and can satisfy a peer dependency with its own peerDependencies; any other package pins every version.
potentialDirectories	"warn"	How a workspaces glob matching a directory that holds no package.json is reported.

library

Accepted values:

Value	Meaning
"auto" (default)	Derived from the package.json: a workspace root or a private package is not a library, anything else is.
true / false	Every package checked with this config entry is, or is not, a library.
string[]	Package name patterns: * matches any characters, a ! prefix excludes, and the last matching pattern wins. A package matching no pattern is not a library.

A single package published to npm needs no setting at all: "auto" detects it. Set the value explicitly when the detection is wrong for you — a package that is published but should still pin every version, or one that is not private yet not consumed by anything:

export default [
  checkPackageDependenciesPlugin.configs.recommended,
  {
    files: ["**/package.json"],
    settings: {
      "check-package-dependencies": { library: false },
    },
  },
];
Copy

In a monorepo, use the **/package.json glob the configs themselves use, so the setting applies to the root and to every member:

export default [
  checkPackageDependenciesPlugin.configs.recommended,
  {
    files: ["**/package.json"],
    settings: {
      "check-package-dependencies": {
        // everything under @scope is published, except the apps and the examples
        library: ["@scope/*", "!@scope/app-*", "!@scope/*-example"],
      },
    },
  },
];
Copy

The setting is resolved against the package.json being linted, so in a monorepo it has to hold for every package the config applies to: a list of patterns, or "auto", is what a monorepo mixing published and private packages wants — a plain true would make the root a library too.

That also means scoping the setting to a member with files does not fully work:

export default [
  checkPackageDependenciesPlugin.configs.recommended,
  {
    files: ["**/package.json"],
    settings: { "check-package-dependencies": { library: true } },
  },
  {
    // applies when linting packages/app/package.json itself, but the root's
    // consistent-workspace-dependencies still classifies it with library: true above
    files: ["packages/app/package.json"],
    settings: { "check-package-dependencies": { library: false } },
  },
];
Copy

Prefer a list of patterns, which gives the same answer wherever the package is resolved from. Note that a list replaces the detection entirely: private is no longer taken into account, so a private package matching a pattern is a library, and the root is only excluded if its name matches no pattern (or is excluded with !).

potentialDirectories

A workspaces glob such as packages/* also matches directories that are not a package. Such a directory is always skipped; the setting only decides how it is reported:

Value	Meaning
"warn" (default)	Logged with console.warn, so it reaches neither the eslint formatter, nor --quiet, nor the exit code.
"off"	Not reported at all.
"error"	Reported as a lint error on the linted package.json, by the rule that loaded the workspace members.

The workspace members are loaded for every linted package.json, so a monorepo repeats the message once per package it lints. Use "off" when a glob is knowingly wider than the packages it matches, or "error" to make a stray directory fail the lint:

export default [
  checkPackageDependenciesPlugin.configs.recommended,
  {
    files: ["**/package.json"],
    settings: {
      "check-package-dependencies": { potentialDirectories: "off" },
    },
  },
];
Copy

Migrating from v12

• The programmatic API is removed: createCheckPackage, createCheckPackageWithWorkspaces and everything they exported are gone, and the package root now exports the eslint plugin, as check-package-dependencies/eslint-plugin already did. Replace a scripts/check-package.js calling checkRecommended() with eslint package.json and the recommended config, or with the cli.
• The cli runs the recommended config through eslint instead of its own checks, so it now requires eslint to be installed. Compared to the checks it replaces:
  • require-workspace-protocol is checked, which the programmatic checkRecommended never did;
  • a dependency on a workspace member declared as a plain range is reported by require-pinned-versions; it was exempted before. Run --fix on require-workspace-protocol to use the workspace: protocol instead;
  • allowRangeVersionsInDependencies has no equivalent: use the library setting.
• The isLibrary option no longer throws, as there is no option left to pass — only the isLibrary setting of the plugin is still reported as renamed to library.

Migrating from v11

• The recommended-library config is removed: use recommended, and let library decide. "auto" covers the usual case; set it explicitly when the detection is wrong for you.
• require-exact-versions is renamed to require-pinned-versions and its dependencies / devDependencies / resolutions options are removed: which fields are checked now follows library.
• The two min-range-* rules are part of recommended, and now report whether or not the package is a library — they were previously only run for a library.
• The isLibrary setting is renamed to library, as it accepts more than a boolean. Using the old name is reported as a lint error once per package.json.
• library defaults to "auto" instead of false. A published, non-private package is therefore checked as a library now: ranges become allowed in its dependencies, and a peer dependency of a dependencies entry must be satisfied by its dependencies or peerDependencies rather than by its devDependencies. Set library: false to keep the previous behaviour.

Rules

💼 Configs enabling the rule: ✅ recommended. A few rules check a library differently, depending on the library setting: see each rule’s page. 🔧 Automatically fixable by the --fix CLI option. 💡 Manually fixable by editor suggestions.

Name	Description	💼	🔧	💡
consistent-workspace-dependencies	Enforce consistent dependency versions across the packages of a workspace	✅	🔧
min-range-dependencies-satisfies-dev-dependencies	Enforce the minimum of a dependencies range to satisfy the version in devDependencies	✅	🔧
min-range-peer-dependencies-satisfies-dependencies	Enforce the minimum of a peerDependencies range to satisfy the version in dependencies	✅	🔧
no-direct-duplicate-dependencies	Disallow dependencies that will be installed twice because a direct dependency requires an incompatible range	✅
no-root-workspace-dependencies	Disallow dependencies in the root package.json of a workspace	✅
require-direct-peer-dependencies	Require peer dependencies of direct dependencies to be present and satisfied	✅
require-identical-versions	Require configured dependencies to have the same version as another dependency of the same package.json
require-identical-versions-as-dependency	Require configured dependencies to have the same version as the one in the dependencies of another dependency
require-identical-versions-as-dev-dependency-of-dependency	Require configured dependencies to have the same version as the one in the devDependencies of another dependency
require-pinned-versions	Require pinned versions in dependencies, devDependencies and resolutions	✅	🔧
require-resolutions-explanation	Require every entry of resolutions to be explained in resolutionsExplained	✅
require-workspace-protocol	Require dependencies on other packages of the workspace to use the workspace: protocol	✅	🔧
resolutions-versions-match	Require resolutions versions to match the versions in dependencies and devDependencies	✅		💡
satisfies-versions	Require configured dependencies to be present and to satisfy the configured ranges			💡
satisfies-versions-between-dependencies	Require the range of a dependency in one dependency to satisfy the range of the same dependency in another dependency
satisfies-versions-from-dependencies	Require configured dependencies to satisfy the ranges declared in the dependencies of another dependency			💡
satisfies-versions-from-dev-dependencies-of-dependency	Require configured dependencies to satisfy the ranges declared in the devDependencies of another dependency			💡
satisfies-versions-in-dependency	Require the dependencies of an installed dependency to satisfy the configured ranges

onlyWarnsFor

Most rules accept an onlyWarnsFor option that downgrades errors to warnings, printed in the console instead of being reported to ESLint. Entries that never matched an error are reported as errors, so the list stays up to date.

Depending on the rule, onlyWarnsFor is either an array of dependency names:

"check-package-dependencies/require-pinned-versions": ["error", { onlyWarnsFor: ["type-fest"] }]
Copy

or a mapping from the dependency causing the error to the dependency names to only warn for, "*" matching any dependency:

"check-package-dependencies/no-direct-duplicate-dependencies": ["error", { onlyWarnsFor: { "*": ["type-fest"] } }]
Copy

Any entry can be written as { name, comment } instead of a bare name, to explain why the exception exists:

"check-package-dependencies/require-pinned-versions": [
  "error",
  {
    onlyWarnsFor: [
      { name: "type-fest", comment: "types only, a range cannot break the build" },
    ],
  },
]
Copy

comment

Every rule accepts a comment, explaining what it is enabled for. It is appended to every message the rule reports, so the reason reaches whoever reads the lint output rather than only whoever opens the config:

"check-package-dependencies/require-resolutions-explanation": [
  "error",
  { comment: "our resolutions outlive the reason we added them" },
]
Copy

The rules configured with a list of dependencies accept one per entry too, which replaces the rule comment in the messages that entry produces — see each rule's page for where it goes:

"check-package-dependencies/satisfies-versions": [
  "error",
  {
    comment: "ranges decided with the platform team",
    devDependencies: {
      eslint: { range: "^10.0.0", comment: "the plugin api changed in 10" },
    },
  },
]
Copy

reports:

error  devDependencies > eslint: Invalid: "9.0.0" should satisfies "^10.0.0" (the plugin api changed in 10)
Copy

Uses Cases

• Check devDependencies are exact versions
• Check resolutions versions matches versions in devDependencies or dependencies
• Check direct peer dependencies are respected, and list exceptions
• Check some dependencies in your package.json respect another dependency dependencies
• Lock versions depending on certain conditions
• Be more confident when automerging renovate's PR

If something is missing for your need, please open an issue !