How can I specify the required Node.js version in package.json?
Solution 1
You can set the engines
field in your package.json
and set requirements for either node
or npm
versions or both:
"engines" : {
"npm" : ">=7.0.0",
"node" : ">=16.0.0"
}
To enforce this via npm you need to create an .npmrc
file (and commit it to the repository) and set the engines-strict
option to true
, which will cause npm commands such as npm install
to fail if the required engine versions to not match:
# .npmrc
engine-strict=true
Without that file, every developer will need to run npm config set engine-strict true
in their local workspace to switch on this option.
Original Answer
As you're saying your code definitely won't work with any lower versions, you probably want the "engineStrict" flag too:
{ "engineStrict" : true }
Documentation for the package.json file can be found on the npmjs site
Update
engineStrict
is now deprecated, so this will only give a warning. It's now down to the user to run npm config set engine-strict true
if they want this.
Update 2
As ben pointed out below, creating a .npmrc
file at the root of your project (the same level as your package.json file) with the text engine-strict=true
will force an error during installation if the Node version is not compatible.
Solution 2
Add the following to package.json
:
"engines": {
"npm": ">=6.0.0",
"node": ">=10.0.0"
},
Add the following to .npmrc
(same directory as package.json
):
engine-strict=true
Solution 3
Just like said Ibam, engineStrict
is now deprecated. But I've found this solution:
check-version.js:
import semver from 'semver';
import { engines } from './package';
const version = engines.node;
if (!semver.satisfies(process.version, version)) {
console.log(`Required node version ${version} not satisfied with current version ${process.version}.`);
process.exit(1);
}
package.json:
{
"name": "my package",
"engines": {
"node": ">=50.9" // intentionally so big version number
},
"scripts": {
"requirements-check": "babel-node check-version.js",
"postinstall": "npm run requirements-check"
}
}
Find out more here: https://medium.com/@adambisek/how-to-check-minimum-required-node-js-version-4a78a8855a0f#.3oslqmig4
.nvmrc
And one more thing. A dotfile '.nvmrc' can be used for requiring specific node version - https://github.com/creationix/nvm#nvmrc
But, it is only respected by npm scripts (and yarn scripts).
Solution 4
.nvmrc
If you are using NVM like this, which you likely should, then you can indicate the nodejs version required for given project in a git-tracked .nvmrc
file:
node --version > .nvmrc
or:
echo v10.15.1 > .nvmrc
This does not take effect automatically on cd
, which is sane: the user must then do a:
nvm use
and now that version of node will be used for the current shell.
You can list the versions of node that you have with:
nvm list
.nvmrc
is documented at: https://github.com/creationix/nvm/tree/02997b0753f66c9790c6016ed022ed2072c22603#nvmrc
How to automatically select that node version on cd
was asked at: Automatically switch to correct version of Node based on project
Tested with NVM 0.33.11.
.nvmrc
vs package.json engines
What you might want to do is:
- use
engines
in package.json to give a "no known incompatibilities range" - give the
.nvmrc
to set a "tested with"
much like package.json vs package-lock.json.
Heroku does respect package.json engines:
Worth mentioning, as documented here, Heroku does play it nice and obey the engines:
entry e.g.:
"engines": {
"node": "14.17.0",
"npm": "6.14.13"
},
So you should Always, Always set that to what you are using locally.
This had been previously mentioned on this self deleted answer to this thread.
Solution 5
There's another, simpler way to do this:
-
npm install Node@8
(saves Node 8 as dependency in package.json) - Your app will run using Node 8 for anyone - even Yarn users!
This works because node
is just a package that ships node as its package binary. It just includes as node_module/.bin which means it only makes node available to package scripts. Not main shell.
See discussion on Twitter here: https://twitter.com/housecor/status/962347301456015360
Erel Segal-Halevi
I am a faculty member in Ariel University, computer science department. My research topic is Fair Division of Land. It is related to the classic problem of fair cake-cutting, which is a multi-disciplinary topic connecting mathematics, economics and computer science, I am always happy to discuss any topic related to land division or fair cake-cutting. If you have a new idea in these topics and need a partner for brain-storming, feel free to email me at [email protected]. The answers I receive in the Stack Exchange websites are very useful, and I often cite them in papers. See my website for examples.
Updated on July 08, 2022Comments
-
Erel Segal-Halevi almost 2 years
I have a Node.js project that requires Node version 12 or higher. Is there a way to specify this in the
packages.json
file, so that the installer will automatically check and inform the users if they need to upgrade? -
Mike Stead over 8 yearsgithub.com/npm/npm/blob/master/CHANGELOG.md#enginestrict "The rarely-used package.json option
engineStrict
has been deprecated for several months, producing warnings when it was used. Starting with npm@3, the value of the field is ignored, and engine violations will only produce warnings. If you, as a user, want strict engines field enforcement, just run npm config set engine-strict true" -
mlunoe almost 8 yearsRemember to
cd .. && npm i <folder-name>
in order to check for the project itself. However, this will trigger a whole build in it self. -
vasilakisfil almost 7 yearswhy on earth they deprecated that.. it looses all its meaning then
-
Brendan Hannemann about 6 yearsI disagree, this would potentially hide the issue and would sideload a different version of node if it wasn't installed.
-
ozanmuyes about 6 years-1 because this is terrible (really terrible) idea. It's like saying that if you are unemployed you should fund a company first and you can start working there.
-
ben almost 6 yearsAdding
engine-strict=true
to your .npmrc now has the same effect -
Jon over 5 yearsSounds like a great idea to me. Separate node versions for separate projects. Can safely upgrade one without upgrading the others. Only catch is have to run in .bin
./node node-sass
rather than justnode-sass
. Not sure if same for all .bin files. -
jcollum over 5 yearsThis is the easiest solution that gives the end user a nice fat error about not having the right version of node when they run
npm install
; works withyarn
as well -
craft over 5 yearsThis is the best answer in 2019, in light of set engine deprecation and the reality that many are (likely) encountering this due to switching versions with nvm.
-
Adrian about 5 yearsThis seems to have no effect at all. I set up my
package.json
with an "engines" section similar to the above (11.13.0
and6.7.0
), and a.npmrc
with nothing but content specified above. I had nvm switch me to an older node version, then rannpm install
, but it just installs the dependencies and doesn't even mention the engine version mismatch. -
Joshua Pinter almost 5 years@ben Perfect, thank you! And this can be committed so that at least your entire team is required to adhere to the engine version requirements.
-
Nathan Bedford over 4 yearsThis is a simple and elegant solution - as long as the team members working on the product know this is happening, I think it's a great answer. We are using this technique at a large company to deal with the variety of Node versions for a dozen web front-end products. Removes the need for constant switching with nvm when going back and forth between products.
-
ivosh over 4 yearsThis solution has its own pros and cons. Node version encapsulation is potentially its biggest pro. The downside is bloated docker image size if you are going to deploy it this way.
-
Ben G over 4 yearsShould not be a unit test, use package.json /dotfiles
-
Joe about 4 years@MikeStead that deprecation is for the package.json directive
engineStrict
and not the user-configurableengine-strict
setting for NPM -
Mike Stead about 4 years@Joe erm yep I was replying to this answer (in 2015) which mentioned
engineStrict
specifically and my reply also mentioned the alternativeengine-strict
npm config option. -
Jamie Nicholl-Shelley about 4 yearsBut whhhhhhhy, a unit test is designed for this >.-
-
ankhzet almost 4 yearsBecause you need Node to run a unit test. If the node version present is too outdated, the tests will simply not run or they'll fail with syntax error or smth. similar, which defeats the point of unit testing. It's like hiding a password reset form behind an authorization form. If you can't remember the password, you need to use reset password function, but now you can't use it, because you don't remember the password.
-
Christopher Camplin over 3 yearsThis assumes @babel/node is installed.
-
Ini over 3 yearsI dont't get a warning on windows when
engine-strict=false
and{ "engineStrict" : true }
-
chharvey over 3 yearsJust to be clear, adding
engine-strict=true
to your own .npmrc file does not enforce anything for your end user, it only enforces you to use the right engine for the packages that you install. There’s nothing you can do to enforce that your end users use the right engine, short of you telling them to add the setting to their .npmrc file. -
chharvey over 3 yearsAdding
engine-strict=true
to your .npmrc file only enforces you to use the right engine when you install packages. It does not enforce anything for your end user. If you want your users to use the engines listed under the"engines: {}"
property in your package.json when they install it, you should tell them to addengine-strict=true
to their .npmrc file. -
Aakash Verma over 3 years
nvm use
doesn't pick up .nvmrc for nvm version 1.1.7 -
Ciro Santilli OurBigBook.com over 3 years@AakashVerma hmmm, on a quick look nvm only goes to version 0.37.2, and nvmrc is still documented on master: github.com/nvm-sh/nvm/tree/… let me know if you figure it out.
-
Ciro Santilli OurBigBook.com over 3 years@AakashVerma I'm guessing you're using github.com/coreybutler/nvm-windows/releases As mentioned on their README "The original nvm is a completely separate project for Mac/Linux only. This project uses an entirely different philosophy and is not just a clone of nvm" so it's not surprising. Consider opening a feature request on their tracker.
-
Aakash Verma over 3 yearsSeems there's a recent PR waiting for this github.com/coreybutler/nvm-windows/pull/594
-
Jamie Nicholl-Shelley about 3 yearsMy assumption being there is at least a minimal packages installed. why else enforce a specific one.
-
Mikel about 3 years@chharvey you could add to the
package.json
the script"preinstall": "echo 'engine-strict=true' >> .npmrc"
-
svandragt over 2 years
engine-strict
usage in.npmrc
is currently not supported by direnv's.envrc
github.com/direnv/direnv/wiki/Node (Found '.nvmrc' with versionengine-strict=true
N/A: version "engine-strict=true -> N/A" is not yet installed. -
rofrol over 2 years
npm install
respectsengine=strict
butyarn install
ignores it -
milahu over 2 yearsmust be
>=12
not>=0.12
-
olawalejuwonm over 2 yearshow can i set this with yarn
-
Abdennour TOUMI over 2 years@JamieNicholl-Shelley Nooooo! unit-test not designed for that! Did you see how go.mod specify the version of go, ... pom.xml specify the version of java! we need the saaaame! got it?
-
Jamie Nicholl-Shelley about 2 yearsHow so? It needs to execute and blocks the runtime if fail. PLus, I mean it's a node project, if you haven't got node installed.. well good luck to you
-
Mocha about 2 yearsBut how do I know the minimum required node version of the node proejct I've made? Please let me know if anyone has a clue. thanks.
-
Rajesh Swarnkar about 2 yearsMay I know what is the deal with node version in
package.json
shown as0.10.0
but in CLI it says10.0.x
? -
Big Rich about 2 yearsAm I misunderstanding something but, couldn't this be installed as a 'dev' dependency, so
npm I -D Node@8
, I'm guessing it wouldn't (shouldn't) then be bundled into a Docker image (or executable), which would simply provide it's own NodeJS runtime, right? -
hellopeach about 2 years@Brendan Hannemann ,why would it not being installed? shouldn't you always run
npm install
at least once before running the app? This is the best solution IMHO as it's basically packaging a virtual environment with the app which means it will always run with exactly the same nodejs environment for everyone as long asnpm install
finished successfully.