Node.js Version Upgrade Prompt

Common errors

• TypeError: pleaseUpgradeNode is not a function

  cause 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'

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

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

Warnings

• breaking 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.
  Fix: Ensure your `package.json` `engines.node` property is in the format `"node": ">=X.Y.Z"` (e.g., `"node": ">=16.0.0"`).
• gotcha 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.
  Fix: Place `require('please-upgrade-node')(pkg)` at the very top of your main executable file, immediately after the shebang (`#!/usr/bin/env node`).
• gotcha 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.
  Fix: For maximum compatibility with older Node.js versions, write the `message` function using ES5 syntax (e.g., `function (requiredVersion) { return '...'; }`).

Install

• npm install please-upgrade-node npm
• yarn add please-upgrade-node yarn
• pnpm add please-upgrade-node pnpm

Imports

• pleaseUpgradeNode
  wrong:

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

  correct:

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

  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)
  wrong:

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

  correct:

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

  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.

Quickstart

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