Setting the Node version in Netlify to fix failing builds

If you've ever run npm audit and discovered some vulnerabilities in your development and/or production environment, the simple solution is usually npm audit fix. But sometimes, you need to upgrade packages to new major versions. And that might involve tweaking your code to adjust for any breaking changes.

I've just done this and was pretty pleased to get down to 0 (known) vulnerabilities. But I wasn't so happy when I broke my Netlify build.

If you want to know how to set the Node version in Netlify without the story, you can set it at Site settings > Build & deploy > Environment. Add a NODE_VERSION key with the version as the value, e.g. 14.18.1.

Thought you could set your prefered Node.js version in your package.json file? Me too, but it won't work on Netlify. Here's how I found that out the hard way!

The fail

I've been using Netlify to host my static sites for years now, with no issues. I would wholeheartedly recommend it to a friend. If it works locally, the Netlify build is usually good too. So, imagine my horror when I went to merge a pull request on GitHub and saw that the Netlify checks had failed. What the?!

I hurried across to Netlify, hands shaking, tiny beads of sweat forming on my forehead. "There must have been a terrible mistake", I thought to myself as I logged in and clicked on the site in question.

And there it was. The sight no coder wants to see. A red tag, and the message Failed.

So I tried again. Retry deploy > Clear cache and deploy site. "Maybe it was a one-off. Maybe next time will be better." I was lying to myself, and I knew it, even before the red Failed tag appeared again.

To be sure my build code was working, I created a fresh clone on Gitpod. Ran npm install and npm run build. Everything worked. So what was going wrong on Netlify?

The problem

It was time to dig into the logs. I took a deep breath and clicked on the failing deploy. The part that was failing had me flummoxed:

12:50:08 PM: import fs from 'fs-extra'
12:50:08 PM:        ^^
12:50:08 PM: SyntaxError: Unexpected identifier

I'm not using an fs-extra package directly, so it must be a dependency of one of the packages I'm using. And it doesn't look like it was the package itself that was the issue. But importing it was. Weird.

But why is it working locally and not on Netlify?

I looked up the logs, looking for a clue, anything that might be different from my local set-up. I saw that Netlify was using Node version 10.24.1, which seemed pretty low.

12:49:12 PM: Downloading and installing node v10.24.1...
12:49:13 PM: Downloading https://nodejs.org/dist/v10.24.1/node-v10.24.1-linux-x64.tar.xz...
...
12:49:15 PM: Now using node v10.24.1 (npm v6.14.12)

"I'm sure I'm using a later version", I thought. I checked the package.json for my repository, and sure enough, I'd specified greater than or equal to 14.18.1:

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

The fix

Well, it turns out, Netlify doesn't get the Node.js version from your package.json file. There's an open feature request, but as things stand at the moment, it doesn't work.

I felt certain that the issue was the Node version. Knowing how Netlify handle builds, I knew there must be an alternative way to set it.

Digging into the Netlify documentation, there are two alternative ways you can specify the Node.js version.

• Set a NODE_VERSION environment variable.
• Add a .node-version or .nvmrc file to the base directory in your repository.

Since the site in question is a monorepo, I need to keep the node version in my package.json file for other services. And I didn't want to have it in two places in my code. So I chose to set the NODE_VERSION environment variable. If you also choose this route, you still need to remember to update the Node.js version specification in two places - your package.json file and the environment variable.

You can set environment variable for your site in Netlify under Site settings > Build & deploy > Environment.

Click Edit variables, then you can add a NODE_VERSION key with the version as the value, e.g. 14.18.1.

Once I had set up the environment variable, I tried again. Retry deploy > Clear cache and deploy site.

And to my absolute delight, green ticks appeared. The build succeeded. I could go ahead and publish the deployment. A good coding story always ends with green, of course!