Registry / devops / please-upgrade-node

please-upgrade-node

library3.2.0jsnpmunverified

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.

devops

npm install please-upgrade-node

github ↗package ↗

INSTALL

IMPORT

SIG · PLEASE-UPGRADE-NOD

please-upgrade-node

devopsjavascriptv3.2.0

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.

pleaseUpgradeNode

✓ const pleaseUpgradeNode = require('please-upgrade-node'); pleaseUpgradeNode(pkg);

✗ import pleaseUpgradeNode from 'please-upgrade-node'; // Not a default export in CJS import { pleaseUpgradeNode } from 'please-upgrade-node'; // Not a named export in CJS

This package is CommonJS-first and exports a function directly. It should be `require`d and then immediately invoked with the package.json object.

Type pleaseUpgradeNode

✓ import type { pleaseUpgradeNodeOptions } from 'please-upgrade-node';

TypeScript types were added in v3.2.0 for better type checking when providing custom options.

pleaseUpgradeNode(pkg, options)

✓ const pleaseUpgradeNode = require('please-upgrade-node'); pleaseUpgradeNode(pkg, { exitCode: 0, message: (v) => `Need Node ${v}` });

✗ pleaseUpgradeNode(pkg, { message: v => `Need Node ${v}` }); // Using ES6 arrow functions in message callback can break on older Node.js versions.

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.

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.

import * as fs from 'node:fs'; import * as path from 'node:path'; const pkgPath = path.join(process.cwd(), 'package.json'); const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')); // Create a dummy package.json for demonstration if it doesn't exist if (!fs.existsSync(pkgPath)) { fs.writeFileSync(pkgPath, JSON.stringify({ name: 'my-cli-app', version: '1.0.0', engines: { node: '>=18' } }, null, 2)); console.log('Created a dummy package.json with engines.node >=18'); } // IMPORTANT: Must run BEFORE requiring any other modules that might use newer Node.js features require('please-upgrade-node')(pkg, { 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`, exitCode: 1 // Default behavior is to exit with code 1 }); // If Node.js version is sufficient, continue with your application logic console.log(` 🎉 Node.js version ${process.version} is sufficient. Running application...\n`); // Your actual application code would follow here

Debug

Known issues

breakingThe `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.

fix

Ensure your `package.json` `engines.node` property is in the format `"node": ">=X.Y.Z"` (e.g., `"node": ">=16.0.0"`).

affects: >=1.0.0

gotchaThe `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.

fix

Place `require('please-upgrade-node')(pkg)` at the very top of your main executable file, immediately after the shebang (`#!/usr/bin/env node`).

affects: >=1.0.0

gotchaWhen 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.

fix

For maximum compatibility with older Node.js versions, write the `message` function using ES5 syntax (e.g., `function (requiredVersion) { return '...'; }`).

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: pleaseUpgradeNode is not a function

Attempting to import `please-upgrade-node` using ESM `import` syntax or an incorrect `require` pattern, instead of directly invoking the default function export.

fix

Use `const pleaseUpgradeNode = require('please-upgrade-node');` and then call `pleaseUpgradeNode(pkg);`. This package is CommonJS-first.

Error: Cannot find module 'please-upgrade-node'

The package has not been installed or is not resolvable in the current environment.

fix

Run `npm install please-upgrade-node` or `yarn add please-upgrade-node` in your project directory.

Application crashes with SyntaxError or ReferenceError on older Node.js versions, despite using please-upgrade-node.

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.

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.

Upgrade

Version history

3.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/typicode/please-upgrade-node ↗

packagehttps://www.npmjs.com/package/please-upgrade-node ↗