How to specify a Node.js version

This article is based on Node v18.13.0

Specifying a Node.js version is important, to reduce issues, especially when working in a big team. There are many more factors to consider, like:

• Compatibility: Different Node.js versions have different features and capabilities.
• Stability: The Node.js ecosystem is moving fast, and new major releases can introduce breaking changes.
• Reproducibility: It's easier to reproduce if the version is specified. For example: If every user in your project has the same version of Node.js you can easier reproduce bugs and solve issues. Also, when you are working on multiple projects, with different node.js versions, it would be a requirement to specify the version.
• Dependencies: Third-party dependencies require a specific node.js version to work properly. A different version can introduce issues with these dependencies.

💰 The Pragmatic Programmer: journey to mastery. 💰 One of the best books in software development, sold over 200,000 times.

Your Single-Page-Application or Node.js Application should be stable, compatible and reliable. Hence, specify the Node.js version and save yourself some headaches.

How to specify your Node.js version?

There are several ways to specify a version. You can add a configuration file for NVM or extend package.json or you write a custom script.

How to specify Node.js when using NVM?

If you installed node with NVM, how to install node.js with NVM, you can simply add a configuration file at the root of your project. This file will also be checked into git, so you can track it.

1. Create a file .nvmrc at the root of your project.

touch .nvmrc

2. Add the required Node.js version to it.

3. If you are already using the required version

node -v > .nvmrc

Otherwise, you can specify it directly in the file, use a text editor of your choice

3. Use the nvm use command to tell NVM to use node version in the configuration file. After using the command the output should be similar to this.

Found '.nvmrc' with version <v18.13.0>
Now using node v18.13.0 (npm v8.19.3)

This approach will not create a warning, when installing dependencies. You have to update your README and inform your team members about the change.

How to specify Node.js version in NPM?

To specify a Node.js version, you can simply add an engines field in your package.json. See NPM docs. Until NPMv3, it was possible to create an .npmrc file to enable engine-strict=true so that it would throw an error when installing dependencies while being on the wrong node.js version. Now, it will not throw an error, but show in the console a warning.

Open your package.json, add the "engines" field and specify the node version. You can use semver to include version ranges or specific limits.

{
  "engines": {
    "node": ">=16.0.0 <17.0.0"
  }
}

Unfortunately, this will only create warning when installing the dependencies. Hence, you have to update your README and inform your team members about the change.

How to specify Node.js version with a custom script?

A good approach would be to combine setting the engine field in your package.json and check if the current node version is within the version range. To do this we can write a simple script in five steps.

1. Specify your desired node version in package.json.

{
  "engines": {
    "node": ">=18.0.0"
  }
}

2. Add a custom engineStrict field to your package.json and set it to true. This field will be read in our custom script. If it's true the script will be executed.

{
  "engineStrict": true
}

3. Install semver and create a file check-node-version.js.

npm i semver
touch check-node-version.js

4. Now, compare the node version in the process with the set version in the engines field. To satisfy semver we can use the semver package.

const semver = require('semver');
const engines = require('./package').engines;

const version = engines.node;
if (!semver.satisfies(process.version, version)) {
  console.log(
    `Required node version ${version} not satisfied with current version ${process.version}.`,
  );
  process.exit(1);
}

5. Update your package.json with a preinstall step and a check-node-version script.

{
  "check-node-version": "node check-node-version.js",
  "preinstall": "npm run check-node-version"
}

And that's it. If you run npm i in your project, and you are on different Node version than specified, the process will exit.

How to specify the Node.js version in React or Angular?

All three approaches from above can be used in React or Angular.

TL;DR

• Your Single-Page-Application or Node.js Application should be stable, compatible and reliable. Hence, specify the Node.js version and save yourself some headaches.
• Create a file .nvmrc at the root of your project, specify version and use with nvm use.
• Add engines field in package.json and specify Node.js version.
• Write a small custom script to compare engines field with Node process and exit if it's not within specified semver range.

Thanks for reading and if you have any questions, use the comment function or send me a message @mariokandut.

If you want to know more about Node, have a look at these Node Tutorials.

References (and Big thanks):

NodeJS, NPM, Adam Bisek