package.json vs package-lock.json: do you need both?

Short Answer is no you don't need both, but maybe you'd want both!

package.json

If your project uses node package manager (NPM) you will have a package.json file somewhere in your code base.

The package.json file records the minimum version of different dependencies that your app needs. When a collaborator on the code does npm install the dependency versions installed will be those dictated in the package.json or a higher/more recent reversion. If you update the versions of a particular package, the change is not necessarily going to be reflected here.

The package.json file is used for more than just dependencies. It also is used to define project properties, descriptions, and license information.

{
  "name": "My-Home-Page",
  "version": "1.0.0",
  "license": "UNLICENSED",
  "author": "Sarah",
  "description": "Sarah's Homepage",
  "keywords": [
    "Home Page",
    ""
  ],
  "homepage": "https://myHomePage.com",
  "repository": {
    "type": "git",
    "url": "https://github.com/YOURREPO"
  },

  "scripts": {
    "start": "gulp startlocal",
  },
  "engines": {
    "node": "^10.2.0",
    "npm": "~6.5.0"
  },
  "dependencies": {
    "angular": "1.8.0",
    "angular-material": "1.4.20",
    "c3": "0.6.11",
    "d3": "3.6.6",
    "jquery": "3.6.7",
    "md5": "2.0.2",
  },

If you look in the example package.json there are ^ and ~. The ^ 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 ~ it will update to latest patch version. This can sometimes cause issues since the collaborators on the same project might all be on different dependency versions.

package-lock.json

Where the package.json file is used for a handful of different things, the package-lock.json file is solely used to "lock" dependencies to a specific version number, including minor and patch versions. It will ignore the ^ and the ~ of the package.json file. This file keeps track of the the exact version of each installed package which means that future installs will be able to build an identical dependency tree.

This is important in some large application spaces with many dependencies. Some dependency versions do not play well with each other, so making sure to "lock in" the versions prevents a lot of issues from occurring. This is especially useful when there are multitudes of individuals collaborating on one code base. In this way, collaborators who npm install 6 months apart will be looking at the same versions getting installed

So you don't need both?

Here's the short answer:
Do you need both package-lock.json and package.json? No.
Do you need the package.json? Yes.
Can you have a project with only the package-lock.json? No.

Should I keep both?

There's a good chance you should! Especially if you keep up with dependency upgrades as needed. It helps to generate the same results on every environment, which will make work flow with many collaborators much easier.

You will want to commit the changes to the package-lock.json as well, so that in deployment npm will be grabbing the same packages as it was grabbing in your local/test environments.

More info

If you want more information about package.json vs package-lock.json this is a great resource.

You can check here to read about NPM audit and checking for known vulnerabilities of the dependencies in your project.

Comments

[Huzaif Qazi]

Thanks! This difference really helped me to understand why lock file is so important ✨

[Isaac Muniz]

Thanks for the simple explanation. :)

[Chris Spurgeon]

This is such a clear explanation! Thanks!

[Sai Sandeep Vaddi]

I always want to keep .lock files.

Sometimes it's a nightmare to update node packages when the project doesn't have .lock file especially when there are no thorough tests.

One time we had an old project which I picked up couple of months later and no lock file. I ran yarn install which apparently installed latest minor version. There were no errors. But, scroll of a virtual list doesn't work. There were no tests to see how many pixels it scrolls on mouse scroll and whether it shows flickering. I tried all the options from the different libraries' docs and checked their git repo issues to see if any of them have anything to do with it. No help. After days of headache, when I installed the version that had released around the time the project was last touched, it magically worked. Lesson learned.