please-upgrade-node

What is please-upgrade-node?

The please-upgrade-node package is designed to help Node.js developers ensure that their applications are run with a minimum required version of Node.js. It provides a simple way to enforce a version constraint, displaying a message to users to upgrade their Node.js version if the current environment does not meet the specified requirements. This is particularly useful for CLI tools or applications where the developer wants to prevent execution in unsupported Node.js environments.

What are please-upgrade-node's main functionalities?

Enforcing minimum Node.js version

This feature allows developers to specify a minimum Node.js version requirement in their package.json file. When the application or tool is run, please-upgrade-node checks the current Node.js version against the specified minimum version. If the current version is lower, it displays a message urging the user to upgrade their Node.js installation. The 'pkg' variable represents the package.json of the application, which should include a 'engines' field specifying the required Node.js version.

require('please-upgrade-node')(pkg)

Other packages similar to please-upgrade-node

check-node-version

Similar to please-upgrade-node, check-node-version allows developers to specify version requirements for Node.js, npm, and Yarn. It can be used as a command-line tool or integrated into scripts. Unlike please-upgrade-node, which is focused solely on Node.js versions, check-node-version provides broader version checking capabilities, making it suitable for projects that also need to enforce npm or Yarn version constraints.

engine-check

engine-check is another package that offers functionality similar to please-upgrade-node by enforcing engine version requirements specified in the package.json file. It can be used as a preinstall or prestart script to ensure that the Node.js environment meets the specified version requirements before proceeding. Compared to please-upgrade-node, engine-check provides a more automated approach to version enforcement, directly integrating with npm lifecycle scripts.

README

Please upgrade Node

Be friendly, be cool :sunglasses: show a message to your users to upgrade Node instead of a stacktrace

It's common for new Node users to miss the npm engines warning when installing a CLI. This package displays a beginner-friendly message if their Node version is below the one expected and it's just a few lines of JS code.

Example with hotel CLI:

$ node -v
0.12
$ hotel
hotel requires at least version 4 of Node, please upgrade

Usage

Install:

npm install please-upgrade-node

yarn add please-upgrade-node

Require please-upgrade-node before anything else:

// bin.js
require('please-upgrade-node')(
  require('./package.json')
)

// The rest of your code...

In your package.json, define the required Node version:

{ 
  "name": "super-cli",
  "bin": "./bin.js",
  "engines": { "node": ">=6" }
}

Please note that >= is the only operator supported by please-upgrade-node (e.g. >=4, >=4.0, >=4.0.0). Now if your users install your super-cli project with an older Node version, they'll see:

$ npm install -g super-cli
# [...]
npm WARN engine super-cli@1.0.0: : wanted: {"node":">=6"} (current: {"node":"4.8.3","npm":"2.15.11"})
# [...]

$ super-cli
super-cli requires at least version 6 of Node, please upgrade

Caveat

Make sure when requiring please-upgrade-node to not use syntax that is only supported in recent versions of Node.

For example, if you use const instead of var and don't transpile it, please-upgrade-node won't work with Node 0.12:

const pkg = require('./package.json') // ← Will fail and exit here with Node 0.12,
                                      // because const isn't supported.
require('please-upgrade-node')(pkg)   // No upgrade message will be displayed :(

See also

• pkg-ok - :ok_hand: Prevents publishing a module with bad paths
• husky - :dog: Git hooks made easy

Thanks to zeit/serve for inspiring the error message.

License

MIT - Typicode :cactus: - Patreon