So yeah I am going to write about probably the most ignored file from our directories package-lock.json !!
package-lock.json is an extremely important file that is there to save you from a lot of boom boom bam bam 🔥 in your repositories.
So before we get into package-lock.json let's talk about semantic versioning and package.json.
Semantic versioning or SemVer is the ideal way of versioning packages. They are usually written like
Includes bug fixes/documentation spelling mistakes etc.
Includes additions of functions or API which does not break anything from the older versions So anything that runs on v1.1.0 should work on v1.9.0 as well.
Includes version which breaks stuff. It can include removing APIs or changing names of functions so anything that works on v1.0.0 may not necessarily work on v2.0.0
package.json is a file that contains information about your project (name, version, etc) and it lists the packages that your project is dependent on.
So as you can see in the picture above after every dependency listed under package.json there's a number something like
^2.20.0 which is the version of that package but before the version, there is
^. So ^ this little guy can be a total destroyer for your project.
^ sign before the version tells npm that if someone clones the project and runs npm install in the directory then install the latest minor version of the package in his node_modules.
So lets say I am having express with
^2.20.0 in package.json and then express team releases version 2.24.0 and now when someone clone my repo and runs
npm install in that directory they will get the version 2.24.0 (You can also put
~ instead of
^ it will update to latest patch version)
However, this can be a huge issue if package developers break any of the functions on the minor version as it can make your application break down.
So npm later released a new file called package-lock.json to avoid such scenarios
package-lock.json will simply avoid this general behavior of installing updated minor version so when someone clones your repo and run npm install in their machine. NPM will look into package-lock.json and install exact versions of the package as the owner has installed so it will ignore the
~ from package.json.
Also, it contains some other meta information which saves time of fetching that data from npm while you do npm install.
You can refer npm blog for some more information on package-lock.json.
Thank You for reading this!
I hope this was useful 🎉 :)
EDIT: So while reading the comments I thought I should also explain how package-lock.json changes so here's one of the replies that I wrote that I think everyone should go through
So I created a project named 'project' and did
npm install --save firstname.lastname@example.org and cloned it three times so there's 'projectclone1', 'projectclone2' and 'projectclone3'
In projectclone1 I have same package.json and package-lock.json as the original project (which means I did not change anything manually) and I run
npm install so it installed the same version as original that is v1.0.0 of vue-extra
In projectclone2 also I had the same package.json and package-lock.json but here instead of doing
npm install I did
npm install --save vue-extra which updated the package changing the package.json and package-lock.json so it installed the latest version that is v1.1.4 of vue-extra
In projectclone3 I opened package.json and manually changed vue-extra:"^1.0.0" to "^1.1.4" and did
npm install, Here since I updated package.json npm considered package.json as a matter of truth and installed v1.1.4 of vue-extra and it also updated package-lock.json to v1.1.4
So if your package.json is somehow changed or updated and the version in package.json does not match with the version in package-lock.json then it will install the version from package.json and will update the package-lock.json accordingly.
I hope this clears up everything
Thanks for reading and asking this question.
EDIT2 : Quoting from the comment of Kat Marchán
(https://dev.to/zkat/comment/epbj) She is the one who wrote
npm ci and added package-lock.json to NPM
Hi! I wrote
npm ci and I'm also the one who added
package-lock.json to NPM back in the day.
The story about package.json vs package-lock.json is tricky:
npm install does not ignore
package.json versions, nor does it ignore the
package-lock.json. What it does is verify that the package.json and package-lock.json correspond to each other. That is, if the semver versions described in
package.json fit with the locked versions in
npm install will use the latter completely, just like
npm ci would.
Now, ff you change
package.json such that the versions in
package-lock.json are no longer valid, your
npm install will be treated as if you'd done
npm install email@example.com, where
x.y.z is the new version in the
This was done intentionally because, after early feedback in
npm@5, we realized that one of the ways people edited their dependencies was by editing
package.json directly, and it became a bit of a usability nightmare to treat
package-lock.json as canonical in those cases. It was a trade-off between two competing worlds, and the current behavior won out.
This is why
npm ci was born: because the behavior for
npm install was actually what people wanted, in practice (when they actually ran into the behavior), and
npm ci had a nice ring to it anyway (it was eventually backronymed to
clean-install for this reason).
Hope this helps! Nice article! 👍🏼