Pin-dependencies-checker NPM

Pin Dependencies Checker CLI

Sometimes you need a reminder for mundane tasks.

Why

When installing dependencies without specifying a version, package managers (yarn, npm, pnpm, etc.) will, by default, install the latest published version with a caret ^:

pnpm add lodash

{
  "dependencies": {
    "lodash": "^4.17.21"
  }
}

This is termed a "ranged" version.

In the lock file, it will be registered that lodash is installed on version 4.17.21 OR HIGHER... and this is where issues arise.

Suppose lodash 4.18.0 is released, and it removes or alters an API our codebase depends on. If I need to regenerate my lockfile for any reason, the package manager will again fetch the latest version 4 of lodash. Instead of installing 4.17.21, it will fetch the new 4.18.0.

If we have unit tests, builds, etc., we'll likely encounter issues without understanding the cause. Our package.json hasn't changed, right? However, it's the lockfile that determines which dependencies get installed.

One way to ensure consistent versions is to avoid installing ranged versions. This can be achieved in various ways depending on the package manager:

pnpm add --save-exact lodash

Or, using pnpm, it can be defined in .npmrc:

save-prefix=''

Alternatively, you can use this tool as a pre-commit reminder to assess all dependencies you've installed and check for ranged versions. 😅

!IMPORTANT
Renovate provides an extensive article detailing the issues with ranged versions. I highly recommend reading it.

How it Works

The process is straightforward:

Scan all package.json files in the current work directory.
Identify all dependencies that:
- aren't valid semver versions (e.g. 1.2.3 or 4.5.6.alpha)
- are URLs or GitHub repositories and don't contain a commitish string neither a semver string
If any are found, the CLI will list them and exit with an error.
Otherwise, it will exit successfully.

Getting Started

You can use this CLI directly from the registry via npx or pnpm dlx:

pnpm dlx pin-dependencies-checker

# OR using npm

npx pin-dependencies-checker

Alternatively, add it to your project's dev dependencies:

pnpm add --save-exact --save-dev pin-dependencies-checker
# Or the equivalent command for your package manager

Then run:

pnpm pin-checker
# Or for npm or yarn
npx pin-checker

Git Hooks

You can automate the CLI execution using a git hook (e.g., pre-commit).

Many JS projects use husky for this purpose.

Simply add the command to your pre-commit script:

# Other commands and setup
pnpm pin-checker

# Or using npx
npx pin-checker

Arguments

By default, this CLI scans only dependencies and devDependencies. This behavior can be modified with CLI arguments.

`--ignore-workspaces`

Default: false

Allows versions starting with workspaces: to be ignored:

pnpm pin-checker --ignore-workspaces

`--ignore-catalog`

Default: false

Allows versions starting with catalog: to be ignored:

pnpm pin-checker --ignore-catalog

See more about pnpm's catalogs feature

`--no-deps`

Default: false

Skips the dependencies evaluation:

pnpm pin-checker --no-deps

`--no-dev-deps`

Default: false

Skips the devDependencies evaluation:

pnpm pin-checker --no-dev-deps

`--peer-deps`

Default: false

Evaluates peerDependencies:

NOTE Peer dependencies are primarily for libraries, indicating to the package manager the necessary version for the library to function correctly. You likely don't want to verify this.