How to specify a Node.js version
© https://nodejs.org/en/

How to specify a Node.js version

If a Node.js version is specified compatibility issues can be avoided.

ByMario Kandut

honey pot logo

Europe’s developer-focused job platform

Let companies apply to you

Developer-focused, salary and tech stack upfront.

Just one profile, no job applications!

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
  1. Add the required Node.js version to it.

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

  1. 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"
  }
}
  1. 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
}
  1. Install semver and create a file check-node-version.js.
npm i semver
touch check-node-version.js
  1. 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);
}
  1. 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

More node articles:

Getting started with Webpack

How to list/debug npm packages?

How to specify a Node.js version

How to create a web server in Node.js

How to dynamically load ESM in CJS

How to convert a CJS module to an ESM

How to create a CJS module

How to stream to an HTTP response

How to handle binary data in Node.js?

How to use streams to ETL data?

How to connect streams with pipeline?

How to handle stream errors?

How to connect streams with pipe?

What Is a Node.js Stream?

Handling Errors in Node (asynchronous)

Handling Errors in Node.js (synchronous)

Introduction to errors in Node.js

Callback to promise-based functions

ETL: Load Data to Destination with Node.js

ETL: Transform Data with Node.js

ETL: Extract Data with Node.js

Event Emitters in Node.js

How to set up SSL locally with Node.js?

How to use async/await in Node.js

What is an API proxy?

How to make an API request in Node.js?

How does the Event Loop work in Node.js

How to wait for multiple Promises?

How to organize Node.js code

Understanding Promises in Node.js

How does the Node.js module system work?

Set up and test a .env file in Node

How to Use Environment Variables in Node

How to clean up node modules?

Restart a Node.js app automatically

How to update a Node dependency - NPM?

What are NPM scripts?

How to uninstall npm packages?

How to install npm packages?

How to create a package.json file?

What Is the Node.js ETL Pipeline?

What is data brokering in Node.js?

How to read and write JSON Files with Node.js?

What is package-lock.json?

How to install Node.js locally with nvm?

How to update Node.js?

How to check unused npm packages?

What is the Node.js fs module?

What is Semantic versioning?

The Basics of Package.json explained

How to patch an NPM dependency

What is NPM audit?

Beginner`s guide to NPM

Getting started with Node.js

Scroll to top ↑