The importance of the package-lock.json file

You probably have seen this file before while working with projects that use Node package manager (NPM).

To be honest, I didn’t pay enough attention to this file before. I knew it was automatically generated and modified when installing dependencies using npm install and I used to delete it and reinstall all dependencies when I had conflicts running my project.

Now we will see why we should give this file the importance it deserves.

We could look at package-lock.json as the older brother of package.json. This brother keeps track of what his younger brother is doing and keeps him out of trouble.

So you may know that package.json is a file that contains information about your project (such as its name, license, author…) and also defines the dependencies that your project needs. Thanks to that, NPM can automatically install all needed dependencies for that project, saving us developers lots of time, as we don´t have to download or commit the node_modules folder.

The package.json file records the minimum version of different dependencies that your app needs.

NPM uses semantic versioning to indicate versions of packages. That means that these numbers are there for a reason.

• First one indicates the major version
• Second number adds new features but doesn’t break the API
• Third one is a bug fix

Following semantic versioning helps other developers understand the extent of changes in a given version, and adjust their own code if necessary.

If you pay attention to the version of dependencies, you will notice two strange symbols:

• The ^ (caret) before the dependency version tells NPM that if someone clones the project and runs npm install it should install the latest minor version.
• If it has a ~ (tilde) it will update to the latest patch version. This can sometimes cause issues since the collaborators on the same project might all be on different dependency versions.

The problem with installing the latest version of a package

Without this older brother (package-lock.json), when one of your teammates clones your repo and does npm install, the dependency versions installed will be those indicated in the package.json or a more recent version.

You may ask yourself why should be this something bad. Well, it may happen that one of the updated packages is not compatible with another package in your project, and this will provoke some conflicts that might break your app, so you won’t be able to start it.

So what package-lock.json does is tell NPM to install the exact same versions you specified in package.json, ignoring the the ^ and ~. Having this file in the repo will assure that everyone is installing the same dependencies, building an identical dependency tree, and therefore getting the same results in different environments.

Conclusion

So I hope you understand that package-lock.json is a safeguard against issues related to differences in dependency versions. It is also useful if you wanted to have that particular version for your dependency during deployment which you used at the time o development

Make sure you don’t change package-lock.json directly and remember that it’s being handled automatically by NPM.

Because of all the above reasons, we should always commit package-lock.json with our project source code so that future setup of the application will not install any available higher version and will install the packages with versions as recorded in the package-lock.json.

This could save you in case of a new release of a module has bugs or vulnerabilities. In that case, you have the possibility to roll back if something breaks.