check-dependencies
v2.0.0
Published
Checks if currently installed npm dependencies are installed in the exact same versions that are specified in package.json
Downloads
134,209
Maintainers
Readme
check-dependencies
Checks if currently installed npm dependencies are installed in the exact same versions that are specified in package.json
Installation
To install the package and add it to your package.json
, invoke:
npm install check-dependencies --save-dev
Rationale
When dependencies are changed in package.json
, whether it's a version bump or a new package, one can forget to invoke npm install
and continue using the application, possibly encountering errors caused by obsolete package versions. To avoid it, use the check-dependencies
module at the top of the entry point of your application; it will inform about not up-to-date setup and optionally install the dependencies.
Another option would be to always invoke npm install
at the top of the main file, but it can be slow and check-dependencies
is fast.
Usage
Once the package has been installed, it may be used via:
CLI
$ check-dependencies
All options from the API except log
and error
can be passed to the CLI, example:
$ check-dependencies --verbose --package-manager pnpm --scope-list dependencies
Options accepting array values in the API (like scopeList
) should have each value passed individually, example:
$ check-dependencies --scope-list dependencies --scope-list devDependencies
API
The exported function returns a promise which should eventually be fulfilled (never rejected).
const output = await require('check-dependencies')(config);
where config
is a configuration object.
output
is an object containing fields:
{
status: number, // 0 if successful, 1 otherwise
depsWereOk: boolean, // true if dependencies were already satisfied
log: array, // array of logged messages
error: array, // array of logged errors
}
There is a synchronous alternative -- the following code:
const output = require('check-dependencies').sync(config);
will assign to output
the same object to which the returned promise would otherwise resolve to.
The config
object may have the following fields:
packageManager
Package manager to check against. Example values: 'npm'
, yarn
, pnpm
.
NOTE: The value passed to this parameter will be invoked if the install
option is set to true
. Do not pass untrusted input here. In the worst case, it may lead to arbitrary code execution! Also, versions below 1.1.1
did no validation of this parameter; versions 1.1.1
and newer ensure it matches the regex /^[a-z][a-z0-9-]*$/i
. It is still not safe to provide untrusted input in versions 1.1.1
or newer, though.
Type: string
Default: 'npm'
packageDir
Path to the directory containing package.json
.
Type: string
Default: the closest directory containing package.json
when going up the tree, starting from the current one
onlySpecified
Ensures all installed dependencies are specified in package.json
.
NOTE: Don't use this option with npm 3.0.0 or newer as it deduplicates the file dependency tree by default so check-dependencies
will think many modules are excessive whereas in fact they will not.
Type: boolean
Default: false
install
Installs packages if they don't match. With the onlySpecified
option enabled it installs if excessive packages are present as well.
Type: boolean
Default: false
scopeList
The list of keys in package.json
where to look for package names & versions.
Type: array
Default: ['dependencies', 'devDependencies']
optionalScopeList
The list of keys in package.json
where to look for optional package names & versions. An optional package is not required to be installed but if it's installed, it's supposed to match the specified version range.
This list is also consulted when using onlySpecified: true
.
Type: array
Default: ['optionalDependencies']
checkGitUrls
By default, check-dependencies will skip version check for packages whose version contains the full repository path. For example:
"dependencies": {
"semver": "https://github.com/npm/node-semver.git#0.5.9"
}
If checkGitUrls is enabled, check-dependencies will parse the version number (after the path to the git repository and the hash) and check it against the version of the installed package.
Type: boolean
Default: false
verbose
Prints messages to the console.
Type: boolean
Default: false
log
A function logging debug messages (applies only if verbose: true
).
Type: function
Default: console.log.bind(console)
error
A function logging error messages (applies only if verbose: true
).
Type: function
Default: console.error.bind(console)
Usage Examples
The most basic usage:
const output = await require('check-dependencies')();
This will check packages' versions and report an error to output
if packages' versions are mismatched.
The following:
await require('check-dependencies')({
install: true,
verbose: true,
});
will install mismatched ones.
Supported Node.js versions
This project aims to support all Node.js versions supported upstream (see Release README for more details).
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using npm test
.
License
Copyright (c) Michał Gołębiowski-Owczarek. Licensed under the MIT license.