Published at
Updated at
Reading time
This post is part of my Today I learned series in which I share all my web development learnings.

Yesterday I reviewed a pull request to Contentful's Gatsby starter and learned a nifty detail about npm configurations.

The pull request's goal was to guarantee that users run the project with a specific Node.js version. You can do so by defining the engines property in your package.json to specify a version range.

  "engines": {
    "node": ">=15.0.0"

But even though many projects define a minimum Node.js version, this package.json configuration is not enforcing the environment. When I run npm install in a project with a not supported Node.js version, the following warning (EBADENGINE) is displayed.

$ npm install

npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE   package: 'engine-test@1.0.0',
npm WARN EBADENGINE   required: { node: '>=15.0.0' },
npm WARN EBADENGINE   current: { node: 'v14.15.0', npm: '7.5.3' }

That's it and all npm does in this scenario. It displays a warning but is not failing and preventing the user from going on.

How to prevent npm install with an unsupported Node.js version

It turns out you can add a local npm configuration file (.npmrc) to your module/project root and explicitly turn on strict Node.js engine handling.


If a project includes an .npmrc that defines a strict engine, people cannot run npm install if their Node.js is not fulfilling the version requirement. ๐ŸŽ‰ The warning EBADENGINE becomes an error, and the installation process fails with a status code 1.

$ npm install

npm ERR! engine Unsupported engine
npm ERR! engine Not compatible with your version of node/npm: engine-test@1.0.0
npm ERR! notsup Not compatible with your version of node/npm: engine-test@1.0.0
npm ERR! notsup Required: {"node":">=15.0.0"}
npm ERR! notsup Actual:   {"npm":"7.5.3","node":"v14.15.0"}

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/stefanjudis/.npm/_logs/2021-02-21T15_34_32_743Z-debug.log

What about Yarn?

Yarn doesn't need an additional configuration file and treats the engines property strictly by default. This seems like the correct way to handle Node.js versions.

$ yarn install

yarn install v1.22.5
info No lockfile found.
[1/5] ๐Ÿ”  Validating package.json...
error engine-test@1.0.0: The engine "node" is incompatible with this module. Expected version ">=15.0.0". Got "14.15.0"
error Found incompatible module.
info Visit for documentation about this command.

And that's all it takes to prevent folks from using your project with an unsupported Node.js version! ๐ŸŽ‰ If you liked this post, make sure to check out my weekly newsletter in which I share more web development learning or have a look at more Node.js posts.

Was this TIL post helpful?
Yes? Cool! You might want to check out Web Weekly for more quick learnings. The last edition went out 8 days ago.
Stefan standing in the park in front of a green background

About Stefan Judis

Frontend nerd with over ten years of experience, freelance dev, "Today I Learned" blogger, conference speaker, and Open Source maintainer.

Related Topics

Related Articles