{"id":11565,"library":"please-upgrade-node","title":"Node.js Version Upgrade Prompt","description":"Please-upgrade-node is a focused utility designed to display a clear, beginner-friendly message to users when their Node.js version does not meet the minimum requirement specified in a project's `package.json` `engines.node` field. Instead of generic stack traces, it provides actionable advice to upgrade Node.js. The package is currently at version 3.2.0, with a recent update adding TypeScript definitions, indicating active maintenance. It is specifically built for CLI applications to enhance user experience by gracefully handling Node.js version incompatibilities. A key differentiator is its strict support for only the `>=` operator in the `engines.node` field, simplifying configuration while ensuring explicit minimum version requirements. Its release cadence is sporadic, tied to feature additions or bug fixes, rather than a fixed schedule.","status":"active","version":"3.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/typicode/please-upgrade-node","tags":["javascript","node","engines","version","check","verify","upgrade"],"install":[{"cmd":"npm install please-upgrade-node","lang":"bash","label":"npm"},{"cmd":"yarn add please-upgrade-node","lang":"bash","label":"yarn"},{"cmd":"pnpm add please-upgrade-node","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is CommonJS-first and exports a function directly. It should be `require`d and then immediately invoked with the package.json object.","wrong":"import pleaseUpgradeNode from 'please-upgrade-node'; // Not a default export in CJS\nimport { pleaseUpgradeNode } from 'please-upgrade-node'; // Not a named export in CJS","symbol":"pleaseUpgradeNode","correct":"const pleaseUpgradeNode = require('please-upgrade-node');\npleaseUpgradeNode(pkg);"},{"note":"TypeScript types were added in v3.2.0 for better type checking when providing custom options.","symbol":"Type pleaseUpgradeNode","correct":"import type { pleaseUpgradeNodeOptions } from 'please-upgrade-node';"},{"note":"When providing a custom `message` function, avoid ES6 features like arrow functions or string interpolation if you need to support very old Node.js versions, as the check itself might fail.","wrong":"pleaseUpgradeNode(pkg, { message: v => `Need Node ${v}` }); // Using ES6 arrow functions in message callback can break on older Node.js versions.","symbol":"pleaseUpgradeNode(pkg, options)","correct":"const pleaseUpgradeNode = require('please-upgrade-node');\npleaseUpgradeNode(pkg, { exitCode: 0, message: (v) => `Need Node ${v}` });"}],"quickstart":{"code":"import * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nconst pkgPath = path.join(process.cwd(), 'package.json');\nconst pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));\n\n// Create a dummy package.json for demonstration if it doesn't exist\nif (!fs.existsSync(pkgPath)) {\n  fs.writeFileSync(pkgPath, JSON.stringify({\n    name: 'my-cli-app',\n    version: '1.0.0',\n    engines: {\n      node: '>=18'\n    }\n  }, null, 2));\n  console.log('Created a dummy package.json with engines.node >=18');\n}\n\n// IMPORTANT: Must run BEFORE requiring any other modules that might use newer Node.js features\nrequire('please-upgrade-node')(pkg, {\n  message: (requiredVersion) => `\\n🚧 Oh no! This application requires Node.js ${requiredVersion} or higher.\\n   You are currently running Node.js ${process.version}.\\n   Please upgrade your Node.js version to continue.\\n`,\n  exitCode: 1 // Default behavior is to exit with code 1\n});\n\n// If Node.js version is sufficient, continue with your application logic\nconsole.log(`\n🎉 Node.js version ${process.version} is sufficient. Running application...\\n`);\n// Your actual application code would follow here\n\n","lang":"typescript","description":"This example demonstrates how to install and integrate `please-upgrade-node` at the very beginning of a CLI application to ensure the user's Node.js version meets the `engines.node` requirement from `package.json`, showing a custom message and exiting if not met."},"warnings":[{"fix":"Ensure your `package.json` `engines.node` property is in the format `\"node\": \">=X.Y.Z\"` (e.g., `\"node\": \">=16.0.0\"`).","message":"The `engines.node` field in `package.json` *must* use the `>=` operator. Other semver operators like `^`, `~`, or specific ranges are not supported and will lead to incorrect behavior or the check being bypassed.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Place `require('please-upgrade-node')(pkg)` at the very top of your main executable file, immediately after the shebang (`#!/usr/bin/env node`).","message":"The `please-upgrade-node` check must be the absolute first executable line in your main CLI entry point, before any other `require` statements or application logic. This is crucial because subsequent modules might throw errors on older Node.js versions before `please-upgrade-node` has a chance to execute and display its friendly message.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For maximum compatibility with older Node.js versions, write the `message` function using ES5 syntax (e.g., `function (requiredVersion) { return '...'; }`).","message":"When providing a custom `message` function in the options, avoid using ES6 features (like arrow functions, `let`/`const`, or template literals) if your `engines.node` target includes Node.js versions that do not fully support those features. The `message` function itself needs to run on the potentially old Node.js version.","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":"Use `const pleaseUpgradeNode = require('please-upgrade-node');` and then call `pleaseUpgradeNode(pkg);`. This package is CommonJS-first.","cause":"Attempting to import `please-upgrade-node` using ESM `import` syntax or an incorrect `require` pattern, instead of directly invoking the default function export.","error":"TypeError: pleaseUpgradeNode is not a function"},{"fix":"Run `npm install please-upgrade-node` or `yarn add please-upgrade-node` in your project directory.","cause":"The package has not been installed or is not resolvable in the current environment.","error":"Error: Cannot find module 'please-upgrade-node'"},{"fix":"Move `require('please-upgrade-node')(pkg)` to the very first line of your CLI entry point, after the shebang, before any other `require` statements.","cause":"The `please-upgrade-node` check was not placed at the absolute top of the file, allowing other modules that use newer JavaScript syntax to be `require`d first.","error":"Application crashes with SyntaxError or ReferenceError on older Node.js versions, despite using please-upgrade-node."}],"ecosystem":"npm"}