What is package-lock.json?

This article is based on Node v16.15.1 and NPM 8.11.0.

This tutorial explains what the difference between package.json and package-lock.json is, and why package-lock.json can help to avoid installing modules with different versions. If you are not sure what the package.json is responsible for, check out this article - The basics of Package.json.

How package-lock.json manages the dependency tree

💰 The Pragmatic Programmer: journey to mastery. 💰 One of the best books in software development, sold over 200,000 times.

package-lock.json is a file generated by npm (since v5 2017), and it locks package dependencies and their sub-dependencies. It tracks only top-level dependencies, and their associated versions. Sounds simple right? Though each of these top-level dependencies can also have their own dependencies, and each of these can also have their own dependencies and so on. This relationship between all the dependencies and sub-dependencies in a project is called the dependency tree. The dependency tree represents every module our project depends on and what version is required.

Installing a dependency with npm actually fetches all the needed dependencies, and installs them into the node_modules/ folder. The package-lock.json file is a snapshot of our entire dependency tree and all the information npm needs to recreate the state of the node_modules/ folder. Also, when a package-lock.json file is present, npm install will install the exact versions specified.

The package-lock.json is not meant to be human-readable, and it's not meant to be edited manually. The npm CLI generates and manages it for us automatically.

Track package-lock.json

The package-lock.json file needs to be committed to version control (GIT) to make sure the same dependency tree is used every time. The benefit of committing the package-lock file to version control is tracking the state of the node_modules/ folder without having to commit the folder itself to version control. Never commit the node-modules folder. It is not intended to be committed, it's too big, and the state is already tracked.

Whenever we run a npm command that changes dependencies, like npm install <PACKAGE> or npm uninstall <PACKAGE> or npm update or any other command that alters dependencies, the package-lock.json file will be updated to reflect the state of the dependency tree.

npm-shrinkwrap

Locking dependencies is not a new concept in the Node.js ecosystem or in the programming world. The package-lock file behaves nearly like the already existing npm-shrinkwrap.json, which was how to lock a package before npm v5. The only difference is that the package-lock.json is ignored by npm when publishing to the NPM registry. If you want to lock your dependencies, when publishing a package you have to use npm-shrinkwrap.json. You should only have one of these files in your root directory. If both are present npm-shrinkwrap takes precedent. The recommended use-case for npm-shrinkwrap.json is applications deployed through the publishing process on the NPM registry.

To create a npm-shrinkwrap file, run npm shrinkwrap. This command renames your package-lock to npm-shrinkwrap. The files are functionally the same. npm-shrinkwrap should be used when publishing to the NPM registry.

TL;DR

• package-lock.json is a snapshot of the entire dependency tree (all packages, all dependencies. all resolved version numbers)
• It's a safeguard against dependency drifting between installs.
• package-lock.json is updated automatically on dependency changes.
• It should be committed to version control to ensure the same dependencies on install.

Thanks for reading and if you have any questions, use the comment function or send me a message @mariokandut.

If you want to know more about Node, have a look at these Node Tutorials.

References (and Big thanks):

NPM package-lock, NPM shrinkwrap, Node, HeyNode