NashTech Insights

Why should we commit package-lock.json to source control? 

Table of Contents

What is the use of package-lock.json file? Perhaps you have seen it in every JavaScript/Typescript source code, but how much do you understand it? And why should we include it in the source control? 

package-lock.json is created whenever we use package.json to manage the dependencies that we use in the project and package.json is managed by npm.

1. Package.json and semantic versioning  

package.json file is used to config npm and this file is important because it declares the libraries, modules and its version. In addition, it helps config libraries options, share your software, publish a package. 

Structure of semantic versioning has the form ‘MAJOR.MINOR.PATCH’ (ex: “happy-dom”: “12.10.1”-> 12 is MAJOR version, 10 is MINOR version and 1 is PATCH version). In a nutshell, when you change your library, you need to announce how the changes will affect the third party, and the version name will show how big the changes are. We can choose to install package in dynamic or static form by using prefix like “^” or “~” or using nothing at all.  

semanctic versioning

2. Manage version between projects 

When you install packages with npm, it will create package-lock.json file which looks like package.json but more verbose because it will list your package’s packages, location of the module (URI),… 

detail about package "happy-dom" in package-lock.json file

Let’s say when we have a repository called A (without package-lock.json file) which has package “happy-dom” with version “^12.10.1” is installed in my machine, you can see it in the package-lock.json. But then tomorrow, the authors fix a bug and release the latest version “12.10.3” of “happy-dom”. And for some reasons, this version is not compatible to your application. A college of yours pull source code and run “npm install”. But since you declare “happy-dom”: “^12.10.1” with a caret (^), it automatically install version 12.10.3 and you know what happens next. You both have the same line “happy-dom”: “^12.10.1” but the versions are different from each other and one application runs smoothly, another is crashed. 

3. How does “package-lock.json” solve the above problem?

When you run “npm install”, npm will read package-lock.json and it will install the version declare in file (in this case the version is “12.10.1”). It’s useful for the future because it will generate the same version everytime. 
* Tip: When you re-install the packages after making changes in package.json but it doesn’t reflect new version. Try to delete node-modules and package-lock.json and then run “npm install” again. 


  • You should commit package-lock.json because it helps stabilize the package’s version. 
  • Remember to re-install your packages when you make a change in dependencies/devDependencies in package.json file.


Leave a Comment

Your email address will not be published. Required fields are marked *

Suggested Article