{"id":14566,"library":"expected-node-version","title":"Expected Node Version","description":"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.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/marcbachmann/expected-node-version","tags":["javascript","node","version","npmrc"],"install":[{"cmd":"npm install expected-node-version","lang":"bash","label":"npm"},{"cmd":"yarn add expected-node-version","lang":"bash","label":"yarn"},{"cmd":"pnpm add expected-node-version","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import expectedNodeVersion from 'expected-node-version';","symbol":"expectedNodeVersion","correct":"const expectedNodeVersion = require('expected-node-version');"}],"quickstart":{"code":"const expectedNodeVersion = require('expected-node-version');\nconst path = require('path');\nconst fs = require('fs');\n\n// Create a temporary directory for testing\nconst tempDir = path.join(__dirname, 'temp_node_version_test');\nfs.mkdirSync(tempDir, { recursive: true });\n\ntry {\n  // Scenario 1: .nvmrc file\n  const nvmrcPath = path.join(tempDir, '.nvmrc');\n  fs.writeFileSync(nvmrcPath, '18.17.1\\n');\n  const versionFromNvmrc = expectedNodeVersion(tempDir);\n  console.log(`Version from .nvmrc in '${tempDir}': ${versionFromNvmrc}`); // Expected: 18.17.1\n  fs.unlinkSync(nvmrcPath);\n\n  // Scenario 2: package.json engines.node\n  const packageJsonPath = path.join(tempDir, 'package.json');\n  fs.writeFileSync(packageJsonPath, JSON.stringify({\n    name: 'test-project',\n    engines: {\n      node: '>=16.0.0 <20.0.0'\n    }\n  }, null, 2));\n  const versionFromPackageJson = expectedNodeVersion(tempDir);\n  console.log(`Version from package.json in '${tempDir}': ${versionFromPackageJson}`); // Expected: >=16.0.0 <20.0.0\n  fs.unlinkSync(packageJsonPath);\n\n  // Scenario 3: Environment variable (simulated)\n  // This is checked globally, so setting it before calling without a path argument\n  process.env.npm_package_engines_node = '20.x';\n  const versionFromEnv = expectedNodeVersion(); // No path, checks process.env first\n  console.log(`Version from environment variable: ${versionFromEnv}`); // Expected: 20.x\n  delete process.env.npm_package_engines_node; // Clean up env var\n\n  // Scenario 4: No version found\n  const noVersion = expectedNodeVersion(tempDir);\n  console.log(`Version when no file found in '${tempDir}': ${noVersion || 'Not found'}`); // Expected: Not found\n\n} finally {\n  // Clean up the temporary directory\n  fs.rmSync(tempDir, { recursive: true, force: true });\n  console.log(`Cleaned up temporary directory: ${tempDir}`);\n}","lang":"javascript","description":"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."},"warnings":[{"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.","message":"This 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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 */ }`","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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).","cause":"Attempting to use `require` in an ES module (ESM) context without proper configuration for CJS interoperability.","error":"TypeError: require is not a function"},{"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.'); }`","cause":"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`.","error":"TypeError: Cannot read properties of null (reading 'startsWith') (or similar error when operating on the returned version)"}],"ecosystem":"npm"}