Information and change management of package.json vs package-lock.json in Node apps

Question

Please note: there are many similar questions here however I do believe I am truly asking a new + unique question.

---

I am new to Node and JavaScript and I am trying to understand the different uses of package.json and package-lock.json. Before you read any further, no, I am not merely just asking for a summary of what their difference is here.

After doing some homework, my understanding of them is as follows:

• you want to commit both to source control, so neither should be mentioned in the .gitignore
• package.json describes your project and can do some lightweight dependency management, for instance, specifying that you want the latest version of the fizzbuzz package, or you want the latest 3.10.x version of the fizzbuzz package
• package-lock.json is purely for dependency management and goes into detail about which specific dependencies your project should use; for instance if you specify you want the latest 3.10.x version of fizzbuzz in your package.json file, the package-lock.json file might specify fizzbuzz-3.10.24, etc.
• you do directly modify/edit your package.json file, but you only let NPM and perhaps other command line tools modify your package-lock.json (hence no human being should ever edit package-lock.json)

Are these statements correct? If not, can someone please provide some details as to how/where my understanding is going awry?

Answer 1

Small answer

Your understanding is correct.

To run a basic Nodejs project you only need package.json file on your project, I mean it's required.

The package.json is used to keep the dependencies of the project. Which also defines project properties like description, author, license information, scripts, etc.

The package-lock.json is used to keep dependencies in a specific version number. It records the exact version of each installed package which allows you to install the same version of packages on different environments.

Brief answer

Why package-lock.json is created?

When you install a package in your project using the below command. for example

npm install node-sass --save

, it will install the exact latest version of that package in your project and save the dependency in the package.json with a carat (^) sign.

"node-sass": "^6.0.0"

Carat (^) means it will support any higher version with the major version. Here, package-lock.json is created for locking the dependency with the installed version, in this case 6.

What is the use of package-lock.json?

As mentioned above it records the exact version of each installed package which allows you to re-install them. This allows you to generate the same results in different environments. For that, we should use the package-lock.json file to install dependencies.

Why should we commit package-lock.json with our project source code (to Git)?

During deployment, when you run npm i (or npm install) on your server or whatever environment with the same package.json file without the package-lock.json, the installed packages might have a higher version now from what you had intended. In that case, if your code targeted a specific version of some of those packages you might have a problem.

References

https://docs.npmjs.com/cli/v7/configuring-npm/package-lock-json