Registry / devops / expected-node-version

expected-node-version

JSON →
library1.0.2jsnpmunverified

The `expected-node-version` package provides a utility to programmatically retrieve the expected Node.js version for a project. It prioritizes speed and common configuration practices by checking environment variables (specifically `npm_package_engines_node` which is set by `npm start`), followed by the `.nvmrc` file, and finally the `engines.node` field within the `package.json`. This specific load order ensures that the most direct and often project-specific version is identified quickly. The current stable version is 1.0.2, with recent minor updates indicating active maintenance, though not a rapid release cycle. Its primary use case is for tools or scripts that need to determine the project's intended Node.js runtime without parsing multiple files manually, streamlining environment checks and ensuring compatibility. It simplifies the process of aligning development environments with project requirements.

npm install expected-node-version
INSTALL
IMPORT
SIG · EXPECTED-NODE-VERS
E
expected-node-version
devopsjavascriptv1.0.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

expectedNodeVersion
const expectedNodeVersion = require('expected-node-version');
import expectedNodeVersion from 'expected-node-version';
This package is exclusively CommonJS and does not provide ES module exports. Using 'import' will result in a runtime error in pure ESM projects unless configured for interop.

Demonstrates how `expected-node-version` retrieves the Node.js version from different sources (environment variable, .nvmrc, package.json engines) following its defined load order. The example creates and cleans up temporary files to simulate different project configurations and showcases how the function prioritizes its checks.

const expectedNodeVersion = require('expected-node-version'); const path = require('path'); const fs = require('fs'); // Create a temporary directory for testing const tempDir = path.join(__dirname, 'temp_node_version_test'); fs.mkdirSync(tempDir, { recursive: true }); try { // Scenario 1: .nvmrc file const nvmrcPath = path.join(tempDir, '.nvmrc'); fs.writeFileSync(nvmrcPath, '18.17.1\n'); const versionFromNvmrc = expectedNodeVersion(tempDir); console.log(`Version from .nvmrc in '${tempDir}': ${versionFromNvmrc}`); // Expected: 18.17.1 fs.unlinkSync(nvmrcPath); // Scenario 2: package.json engines.node const packageJsonPath = path.join(tempDir, 'package.json'); fs.writeFileSync(packageJsonPath, JSON.stringify({ name: 'test-project', engines: { node: '>=16.0.0 <20.0.0' } }, null, 2)); const versionFromPackageJson = expectedNodeVersion(tempDir); console.log(`Version from package.json in '${tempDir}': ${versionFromPackageJson}`); // Expected: >=16.0.0 <20.0.0 fs.unlinkSync(packageJsonPath); // Scenario 3: Environment variable (simulated) // This is checked globally, so setting it before calling without a path argument process.env.npm_package_engines_node = '20.x'; const versionFromEnv = expectedNodeVersion(); // No path, checks process.env first console.log(`Version from environment variable: ${versionFromEnv}`); // Expected: 20.x delete process.env.npm_package_engines_node; // Clean up env var // Scenario 4: No version found const noVersion = expectedNodeVersion(tempDir); console.log(`Version when no file found in '${tempDir}': ${noVersion || 'Not found'}`); // Expected: Not found } finally { // Clean up the temporary directory fs.rmSync(tempDir, { recursive: true, force: true }); console.log(`Cleaned up temporary directory: ${tempDir}`); }
Debug
Known issues
gotchaThis package is CommonJS-only. In pure ES module (ESM) environments, direct `import` statements for `expected-node-version` will fail at runtime. It can be used in hybrid ESM/CJS projects or by explicitly configuring an ESM loader for CJS interop, but this adds complexity.
fix
For ESM projects, consider using a dynamic `import()` or ensuring your build/runtime environment is configured for CommonJS interoperability. Alternatively, wrap the `require` call in a separate CJS file and import that wrapper.
affects: >=1.0.0
gotchaThe utility determines the Node.js version based on a specific load order: `npm_package_engines_node` environment variable, then `.nvmrc` file, and finally `package.json`'s `engines.node` field. Be aware that environment variables take precedence over file-based configurations, which might lead to unexpected results if not understood.
fix
Understand the priority to ensure the correct version is being retrieved. If an unexpected version is returned, thoroughly check environment variables first, then `.nvmrc`, then `package.json`.
affects: >=1.0.0
gotchaThe function returns `null` if no expected Node.js version can be found in any of the checked locations. It does not throw an error in this scenario, requiring explicit handling of the `null` return.
fix
Always implement a null-check after calling `expectedNodeVersion()` to gracefully handle cases where no version is specified, e.g., `const version = expectedNodeVersion(); if (version) { /* use version */ } else { /* handle no version found */ }`
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: require is not a function
Attempting to use `require` in an ES module (ESM) context without proper configuration for CJS interoperability.
fix
If running in an ESM context, consider using a dynamic `import()` for CJS modules, or ensure your `package.json` is configured for CommonJS (e.g., by omitting `"type": "module"` or using `.cjs` extensions).
TypeError: Cannot read properties of null (reading 'startsWith') (or similar error when operating on the returned version)
The `expectedNodeVersion` function returned `null` because no Node.js version was found in the expected locations (environment, `.nvmrc`, `package.json`), and subsequent code tried to operate on `null`.
fix
Implement a null-check before using the returned value: `const version = expectedNodeVersion(); if (version) { /* proceed with version */ } else { console.warn('No expected Node.js version found.'); }`
Upgrade
Version history
1.0.2latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources
expected-node-version — npm install expected-node-version · libregistry