Problem
{
"dependencies": {
"some_module": "^0.3.8",
"some_other_module": "~0.1.3",
"dont_do_this": "*"
}
}
Do any of those patterns look familiar to you? Yes? Then I sure hope you know whether all of your installed packages follow semantic versioning (semver)! Otherwise these could be ticking time bombs waiting to blow up in your future deployment.
Some packages follow semver better than others, but, from my experience, the ones you should be most cautious with are the sub-1.0 packages because they definitely don't follow semver; they typically use the second digit (0.x) as the major version and the third digit (0.1.x) as the patch or feature version! So the next time you run your build for a package in version 0.x
you might be in for a nasty surprise.
For a more concrete example, let's use knex
, which is currently in version 0.16.3
. Now, if you specify in your package.json
to install version 0.x
, then this means that the next time you run a deployment you could be installing version 0.17.0
, which might contain breaking changes that impact your app!
Solution
At this point, you might be wondering how you could solve this problem. Luckily for us, the solution is pretty simple: lock down all of the package versions! Your package.json
should look more like the one below to avoid any surprises.
{
"dependencies": {
"some_module": "0.3.8",
"some_other_module": "0.1.3",
}
}
Of course, you can also relax the rules for any packages that you know follow semver. For instance, you're probably safe to trust packages like react
(v16.8.2) and restify
(v7.7.0) since they're both pretty popular projects with many major releases.
Edit
As mentioned in the discussion, this issue can also be mitigated by keeping your package-lock.json up to date. This works because once a version is specified in the package-lock.json, it won't be updated if it meets the required version specified in package.json. For instance, 0.24.0 fulfills the requirement for 0.x, so even if 0.25.0 is released, npm will continue to install and use 0.24.0.
References
https://docs.npmjs.com/about-semantic-versioning
https://docs.npmjs.com/files/package-locks
Top comments (20)
Yep, what you've stated is #4 of the official specification for Semantic Versioning:
This issue isn't exclusive to NPM either, packages via Composer or Nuget are the same if they follow the specification.
Thanks for pointing this out. I wasn't aware that the official spec allows for a major version to be 0 for initial development. Although, I have seen many major packages (knex, soap, axios) remain in 'initial development' phases for years. So I think this could still cause problems for unsuspecting developers.
So is not really and issue but a feature. Great!
It’s just another case of “Don’t get too comfortable doing this.”.
Or just use the automatic package-lock.json like everyone else...
Good point. I was under the impression that when a new version of the package is released, the dependency tree would be regenerated for the newest version. But after running some tests, it looks like that's not the case; once a version is specified in the package-lock.json, it won't be updated if it fulfills the required version; E.g., 0.24.0 fulfills the requirement for 0.x, so even if 0.25.0 is released, npm will continue to install and use 0.24.0.
That hasn't always been the case, and if that is what you want that is why they recommend using
npm ci
instead ofnpm install
so that package-lock.json will absolutely dictate which dependencies you install.I mean,even if in theory
npm install
installs based on package-lock.json, it hasn't always been the case, and has varied from version to version ofnpm
, and once you have a valid package-lock.json,npm ci
is THE way to guarantee you are installing based on it.No good, I know!
Yep, otherwise package-lock.json would be totally useless
For projects that stay in major 0 for too long, use
~0.x.y
instead of^0.x.y
.Locking them down to
0.x.y
is basically always overkill until something literally breaks.And, to just parrot everyone else in the comments, shrinkwrap and have tests :)
I remember a case at one of my earlier workplaces, the first workplace where I used node.js (think it was v0.6 back then). We where 5 people using the same code-base and three out of us could not start the application, it blew up in a module which we all had at the same version!
After hours of debugging and trying to figure out what was wrong, we noticed that one of the dependencies of the dependencies dependency had a patch version added (It went from like... 1.2.3 to 1.2.3-1), a patch which broke the API totally...
I no longer trust peoples versioning and always try to stick to using SEMVER on my own projects...
:P
My personal preference is to have good test coverage and then auto-update with a tool like renovate.
Agree this can be very frustrating. There was few times when a developer can't reproduce behavior which can see other developer because of this. Locked versions long time ago in our projects. We use npm upgrade tools for controlled packages upgrade...
I am just wondering - is there a downside to doing this locking down of dependencies by default?
Yes. You cannot use
npm update
to automatically update based on the semver. I prefer using package-lock.json to lock versions.Thanks. Will look more into it.
Since when has npm implemented lock files? I've been waiting years before switching to yarn.
Are you still not on
pnpm
? 😲😲For some time now. It's been the default for at least a year.
Not for long then. Well, too late anyway.