package-lock.json seems like a really, really dull file. And ideally, it is.
It is like the keys on your keyboard which you don't notice until they get crunchy (looking at you butterfly and silicon-based keyboards).
But do enough
package installs and you'll run into issues. This article is a high-level overview of the what and the why of
package-lock.json so you can debug with understanding.
The purpose of the
package-lock.json is to let every developer on a repo have the same package tree, meaning each developer has the exact same packages and all dependencies versions as you, even if there are new packages available.
Depending on how the
package.json is written, an
npm install command could install a more recent patch, a minor update, or the exact same package. If the packages and their dependencies are different, it might not cause an issue….or it might.
package-lock.json is used by NPM when you
npm install and the lock file is set in digital stone; whereas,
package.json just indicates major package dependencies, how to handle updates and is meant to be changed by a developer.
package.json as what you want to install and the
lock file as what exactly and precisely was installed.
A key part of package version control is with SemVer specs. aka Semantic Versioning. aka v.
a is the major version, breaking backward compatibility.
b is new features but doesn’t change current features
c is a bug fix
So why do you care? If you run into issues on
npm install, likely you have a version issue.
For now, just know this (the relationship is explained in the next section):
^, or lack of, dictate how and when a repo’s direct dependencies update.
- if you write ~0.13.0, you want only update patch releases: 0.13.1 is ok, but 0.14.0 is not.
- if you write ^0.13.0, you want to update patch and minor releases: 0.13.1, 0.14.0 and so on.
- if you write 0.13.0, that is the exact version that will be used, always
- Source: nodejs.dev
npm install a repo without a
package-lock.json, NPM “knows” to install the latest version of the packages within the minor release.
That is, if a semantic version (aka semver) is ^0.13.0 for package X, NPM won’t install version 1.0.0 (assuming a developer follows semver specs), but it might install 0.15.0 as the latest version. And while 0.15.0 should be compatible with 0.13.0 features, it might introduce a bug.
This is where the
package-lock.json comes in handy.
npm install a repo with a
package-lock.json, npm “knows” to install all the packages and versions dictated in the lock file. Since the lock file is committed to source control, everyone will have the same packages and package dependencies. #magic
Tip: If you are doing a tutorial from scratch and run into issues with packages, make sure you can at least use the same
package-lock.json files from their repo.
- Automatically generated when NPM changes node_modules tree or the package.json file is changed.
- It should be committed into your source repo.
- It is ignored if found anywhere else other than in top-level folder structure.
- Didn’t exist before version NPM v5.
package.jsondictates what is in
package-lock.jsonas of PR17508.
Did I miss something? Should I add something other devs should know? Drop a comment and I'll update the article with the appropriate information (and citation).