How to Change the Node Version for Netlify Builds

Some of you may know that this site is hosted on Netlify. But recently I was experiencing weird issues with different environments and the source not always building consistently across multiple machines. Obviously the build system that runs when Netlify detects a change to the source code or a triggered build is fired when I’ve created a new article, would be another system that needs to build the repository. After a lot of digging, I started to realize that this solution only optimally runs on a very specific version of Node and NPM.

Specifying Engine Details in NPM

So I needed a way to instruct those that are trying to build my repository for this site, to tell it specifically what version of npm/node to use. I found that this is quite easy to do, but requires some configuration in your package.json:

1{
2  "engines": {
3    "node": ">=0.10.3 <15",
4    "npm": ">=1.0.20"
5  }
6}

For more information about this, you can refer to the documentation available from NPM.

Once you’ve configured the engines in your package.json, you’ll also want to look at creating a .npmrc file to control when this engine definition is enforced (otherwise its just optional and will display a friendlier warning in the console when you try to do a build, vs blocking the build if it’s set to strict).

1engine-strict=true

What about ensuring Netlify builds with the correct version?

So the details that we specified above are great, especially if we want to ensure every developer working on our project is using the same requirements to run and work on the solution. In fact, I would say that if you are starting a new project, you will almost certainly want to provide this detail to ensure everyone is using the correct version. But even after making those changes above, I found that the Netlify builds were still using the default 12.x node version to do my builds for my project. So what am I missing?

Well, it turns out I needed, at least for Netlify, to create a new file .nvmrc. Now NVM (Node Version Manager), if you’ve never used this before, this is also an almost necessity if you are developing with node locally because each project that you are building locally could easily require a different node or npm version. NVM solves all of those issues by managing multiple versions of Node on your machine. If you need to switch to a different node version, you can simply either install that version using nvm install 12.x.x or whatever the version may be, but also you can use the nvm list command to see a list of all the installed versions of npm/node that NVM is managing for you.

But either way, it appears that the Netlify build is using NVM as well to manage which version of node/npm to run. So now it’s actually quite easy to just specify the version we need in our .nvmrc file:

1v14.16.1

Once I committed that change, I was now seeing that the Netlify builds were downloading if the build agent hadn’t already installed that version, and if it had, it would go ahead and use the version that I specified. Pretty neat stuff, so at the end of this, I can now ensure that local development is using the correct versions of npm/node, as well as the Netlify build servers. Now I can take on a feature task in my repository to ensure it works with the latest lts of node/npm and then update everything to match that version.

Extra Credit

So I was thinking about how this behavior of using nvm use works for our Netlify builds but for some reason it doesn’t seem to be working for nvm-windows. After some quick googling, I came across this post, provides an alias work around which gives the same outcome, since this functionality of the nvm use command, picking up the current .nvmrc file is only supported in Linux. So definitely something worth adding, so the next time you work on a node/npm project, you can just run your simple alias command, and start using the specific versions of both engines immediately. Pretty cool!