How to Lock down Your Project’s Node Version Using .Nvmrc Or engines.

Ng'etich Faith
3 min readMay 27, 2018

What is locking down a specific node version?

This is the process of using a lockdown tool to isolate the dependencies of your node.js app’s specific version.

Why is it important?

  • Your project is totally locked down and is completely available offline. Thus it is much quicker to install.
  • I am going to walk you through a simple process of locking down a Node.js application using .nvmrc and also using engines. In the first part, I am going to assume that you use Node Version Manager (nvm). In case you are interested in adding this, the nvm readme is pretty descriptive, which makes installing the manager straightforward.

Using .nvmrc

  • In your project, create a.nvmrc file to add the node version. You can use the nvm —-help to check other options. In this tutorial, we are going to use node version 8.9.0.
touch .nvmrc
  • Add this line 8.9.0 to the .nvmrc file.
  • Afterwards, run the commands below:
nvm usenvm installnvm execnvm runnvm which
  • nvm use looks for the .nvmrc and utilizes it. Remember, no trailing . spaces are allowed. A new line is required.

Using engines

  • Because some project collaborators prefer not to use a version manager, using engines is the preferred way to lock down a specific node version , which covers this edge case.
  • We are going to use engine-strict which uses Semantic Versioning(Semver).
  • Semver is a 3 component system in the format of a.b.c where a is the major version, b the minor version, and c is the patch. This format is really helpful in managing dependencies, which is why we are going to use it to specify our project’s node version.
  • Run this command in your terminal to install semver.
npm install semver
  • In your package.json you should see "server" : "^5.5.0" added or a later version.
  • We are going to write a script to check that our project’s node version is at-least 8.9.0 or above.
  • Create a file and name it check_node_version.js
touch check_node_version.js
  • Then add the following simple lines of code.
const semver = require (‘semver’);
const { engines } = require (‘./package’);
const version = engines.node;
if (!semver.satisfies(process.version, version)) {
throw new Error(`The current node version${process.version} does not satisfy the required version ${version} .`);
  • You need to specify the node engine you would like to use in your package.json. Add the following lines of code in thepackage.json file that runs the script.
"engineStrict": true,
"engines": {
"node": ">=8.9.0"
“scripts”: {
"requirements-check”: “node check_node_version.js”,
“test”: “bundle exec rake cucumber && bundle exec rake rspec && bundle exec rake jasmine:ci”,
“postinstall”: “./node_modules/bower/bin/bower install && npm run requirements-check”
  • Finally run npm install to confirm that your setup is working. This command will only work if you have a node version that is 8.9.0 or higher. In case you have a lower version, you need to upgrade to 8.9.0 or a later version for this command to run successfully.