Registry / devops / check-node-version

check-node-version

library4.2.1jsnpmunverified

check-node-version is a utility designed to verify that the currently installed versions of Node.js and various package managers (npm, npx, yarn, and pnpm) meet specified semantic version ranges. It operates both as a command-line interface (CLI) tool for script automation and offers a programmatic API for integration into applications. The current stable version is 4.2.1, indicating a mature and well-established package. Its primary function is to prevent common environment-related issues by providing clear feedback and suggested installation steps (e.g., using `nvm`) when version requirements are not met. This makes it a crucial tool for maintaining consistent development and deployment environments across teams and CI/CD pipelines, differing from simple `node -v` by offering comprehensive checks and actionable advice for multiple tools.

devops testing

npm install check-node-version

github ↗package ↗

INSTALL

IMPORT

SIG · CHECK-NODE-VERSION

check-node-version

devopsjavascriptv4.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

check

✓ import check from 'check-node-version';

✗ import { check } from 'check-node-version';

The primary export is a default function. Type definitions are included for TypeScript.

check (CommonJS)

✓ const check = require('check-node-version');

CommonJS require syntax for Node.js environments. The function itself is named 'check' in documentation.

CliOptions

✓ import type { CliOptions } from 'check-node-version';

Importing type definitions for programmatic usage, common in TypeScript projects.

This quickstart demonstrates the programmatic API to check Node.js, npm, and yarn versions. It logs success or lists unsatisfied versions with suggested fixes, exiting with an appropriate status code.

import check from 'check-node-version'; const requiredVersions = { node: '>=18.0.0', npm: '>=8.0.0', yarn: '^1.22.0' }; check(requiredVersions, (error, result) => { if (error) { console.error('An unexpected error occurred:', error); process.exit(1); } if (result.isSatisfied) { console.log('All required Node.js and package manager versions are satisfied!'); console.log('Current versions:'); for (const tool in result.versions) { console.log(` ${tool}: ${result.versions[tool].version} (Wanted: ${result.versions[tool].wanted})`); } process.exit(0); } else { console.error('Some required Node.js or package manager versions are NOT satisfied:'); for (const tool in result.versions) { if (!result.versions[tool].isSatisfied) { console.error(` ${tool}: Found ${result.versions[tool].version || 'N/A'} (Wanted: ${result.versions[tool].wanted})`); if (result.versions[tool].notSatisfiedVersion) { console.error(` Suggested fix: ${result.versions[tool].notSatisfiedVersion.message}`); } } } process.exit(1); } });

check-node-version --version

Debug

Known issues

gotchaWhen checking versions of tools like Yarn, if a non-semver-compliant version string is encountered, `check-node-version` may treat it as a 'missing tool' and report an error, rather than attempting to parse an invalid version. This is by design to ensure strict semver adherence.

fix

Ensure all tools (Node.js, npm, npx, yarn, pnpm) are installed with semver-compliant version strings. Update problematic tools if necessary.

affects: >=1.0.0

gotchaUsing the `--package` or `--volta` CLI options (or their programmatic equivalents) will make `check-node-version` strictly adhere to the `engines` field in `package.json` or versions pinned by Volta. This can sometimes lead to failures if the `engines` field specifies a very narrow or outdated range, even if a compatible-but-not-exact version is installed.

fix

Review and update the `engines` field in your `package.json` to reflect realistic and supported version ranges, or ensure Volta pins are current if using `--volta`.

affects: >=1.0.0

gotchaThe suggestions provided by `check-node-version` (e.g., `nvm install X`) are generic and might not be applicable to all environments or operating systems. Users in managed environments, CI/CD pipelines, or specific OS setups might need to use alternative installation methods.

fix

Always verify the appropriate version management or installation method for your specific environment when `check-node-version` reports a version mismatch.

affects: >=1.0.0

breakingThere have been no significant breaking changes introduced within `check-node-version` itself across its major versions that would typically halt or alter its core functionality since its initial stable releases. The package maintains high backward compatibility for its primary use cases. Any 'breaking changes' are usually related to updates in Node.js or package manager versions, not the utility's API.

fix

N/A - This indicates stability; focus on keeping your Node.js ecosystem tools updated.

affects: N/A

Errors

Common errors & fixes

Error: Wanted node version X.X.X (>=X.X.X <Y.Y.Y)

The currently installed Node.js version (or other tool) does not satisfy the specified semantic version range.

fix

Use a version manager (e.g., `nvm install <version>`, `nvm use <version>`) or update your global Node.js/package manager installation to meet the required range. The output typically provides a direct suggestion.

check-node-version: command not found

The `check-node-version` executable is not in your system's PATH, or the package was not installed globally or locally linked correctly.

fix

If installed locally, run with `npx check-node-version ...` or `npm run check-node-version ...` if defined in `package.json` scripts. If intended for global use, ensure it's installed globally: `npm install -g check-node-version`.

Some package version(s) failed!

When using the programmatic API, this message indicates that `result.isSatisfied` was false, meaning one or more of the checked tools did not meet their version requirements.

fix

Inspect the `result.versions` object within your callback to identify which specific tool(s) failed and their respective `notSatisfiedVersion.message` for remediation. The example quickstart code demonstrates this.

Error: Could not parse version X.X.X for Y

The version string reported by tool Y (e.g., Yarn) is not a valid semantic version, preventing `check-node-version` from parsing it correctly.

fix

Update the problematic tool (Y) to a version that reports a semver-compliant string. Some older or custom builds of package managers might exhibit this issue. Alternatively, consider checking only semver-compliant tools or adjusting the check logic if strict semver isn't crucial for that specific tool.

Upgrade

Version history

4.2.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node