Specifying a Node version

In your build instructions for Node apps (Manage build dependencies | Netlify Docs), the recommended way to set a Node version is via a .node-version file or NODE_VERSION env var; and similarly use NPM_VERSION to set the npm version, and YARN_VERSION to set the yarn version.

The standard way to define these (in any Node project) is via the engines key in package.json – see https://docs.npmjs.com/files/package.json#engines

The approach you’re using can lead to a situation where the Node, npm and/or yarn versions used on the developer’s machine are not the same as in a Netlify build, leading to build failures or strange variation.

Don’t Repeat Yourself – this info should be in only one place. It would be better to use the package.json mechanism. If that can’t be done, it would make sense to add a prominent warning to your doc page that I referenced about to say the standard Node approach is IGNORED.


Thanks for bringing this up, @chris-activewrite. We’ll think it over!

Hey Chris!

Really appreciate you taking the time to write this up so thoughtfully! We have an open feature request on this:

If you could add your voice to it there, then you’ll see if we get it implemented automatically :slight_smile:

Is this not a thing yet??
It would really nice since this is the standard way to set Node versions.
I am suprised it’s not already integrated considering JAMstack and all.

Can we please get support for this??

1 Like

No status change here, @ontoneio. We’ll post in this thread if anything changes, of course!

1 Like

Some of our builds are failing. Setting the engine through the package.json would solve the problem. Please consider making this improvement.

1 Like

Wow this really threw me today. Any update?


Hi, @QuantumJS. The feature request is linked to above. I checked the feature request but it is still “open” (meaning the feature request has not be completed yet).

If or when this feature request is added, we will post an update here.

For interest, the .node-version file is also used by other products. I have been collecting usage (and adding netlify).

So, what is the status of this?
The default node netlify uses it’s quite old. Kind of bad experience that your build fails because the CI uses an outdated node version.

We use Node 16 by default which is the latest LTS.

Then why is my build pipeline using node 10 if I don’t have any mechanism to set it? I had to add a npm version file to make it use 17

What site is it? Chances are you started building on Node 10 at first and we don’t upgrade the Node Versions automatically to prevent errors due to breaking changes. All new sites use Node 16 by default, which will likely be pinned too, so they don’t break in future.

I created my project about 2 years ago, and yes, at that time node 10 was the default.

Creating a .nvmrc file fixed this issue: How to specify a Node Version in Netlify | Reactgo