What is package-lock.json?

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

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.

The package-lock specifies exactly the state of your dependency tree to reproduce when installing your project dependencies. It will make sure that you get the exact same version of each dependency and sub-dependency, every time.

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.

💰: $100 (credits) for you to start your cloud journey with DigitalOcean!

References (and Big thanks):

NPM package-lock, NPM shrinkwrap, Node, HeyNode