How to Upgrade an NPM package
November 26th, 2019
TLDR; using npm upgrade <packagename> will often not install the most recent 'Major' release of a package. For this we need to use something like
or specify the version like
Once you have had an NPM package in your project for some time it will most likely fall behind the latest version of the package that is available. First off you'll lag behind as patches are released, then some minor versions will appear and in time a major release version will drop and leave your package looking rather outdated.
So how do you go about upgrading to get all the goodness of the latest version available. Well first let's step back a bit and look at what happens when you initially install your package. For our example we'll use the venerable 'Moment' package which provides all the timing functions you could ever need. To install we would run something like the below:
and that would give us the below in our package.json file:
So what is this telling us? well the version we have installed is 2.24.0. The format of this version is as below:
Major.Minor.Patch
So we are on Major version 2, minor version 24 and patch version 0
The ^ symbol just before the Major version is used as part of the upgrade process. This tells npm that we should happily install new patch versions and also new minor versions anytime that this is requested. But it will prevent us from installing a new Major version (e.g. 3.0.0) without providing explicit consent to do so.
So back to our example let's install an older version so we can look at performing some upgrades. To install a specific version we use the @ symbol after the package name and provide the version we would like. So to get version 1.5.1 we would use:
npm i moment@1.5.1
Now with this installed we can run the upgrade and get the most recent 'Minor' and 'Patch' version that is available
checking our package.json now we should see the below:
So all good and expected.
Now what do we need to do in order to upgrade to the most recent Major version? for this we need to explicitly specify the version we would like. So we could go onto NPM and find out what is the lastest package and then specify this as below:
npm i moment@2.24.0
To remove the pain of having to find this out on the npm website we can simply run npm outdated to see details of the package version we currently have, the version that is 'wanted' and would be installed with npm upgrade, and then also the 'latest' version which will be installed by using the 'latest' tag.
So there is this notion of 'Tags' in npm and by convention the tag of 'latest' can be used to point at the most recent release, removing the need to find it out yourself. So we could simply use the below instead to speed things up
npm i moment@latest
checking package.json again and we should see the below:
There are a few other scenarios that we should be aware of. One of which is to place an asterix in the package.json as below. This tells npm to allow the upgrade to use the latest Major version of the package when running npm upgrade.
One other setting that we might see is ~ which tells npm to only allow upgrades to the patch version. This looks like:
So there we go, clear as mud? hopefully a little better than before you read this anyhow!
Link to YouTube video for a visual walkthrough of the above: