Everything You Wanted To Know About package-lock.json But Were Too Afraid To Ask

You can also read this story on my personal Gatsby blog.

Introduction

So you’ve updated Node Package Manager (npm) to v5.x.x, and everything seems to be going fine. But wait, what’s this? A new file was created automatically. Package-lock.json. If you open it, it looks sort of like the dependencies in package.json, but more verbose. You decide to ignore it and go along your way developing your project. Eventually, you run into problems with a dependency. It can’t be found or the wrong version seems to be installed. Most people just end up deleting the package-lock.json and running `npm install`. So why even have it? What is it supposed to do? What does it actually do?

Summary

• If you’re using npm ^5.x.x, by default a package-lock.json will be generated for you
• You should use package-lock to ensure a consistent install and compatible dependencies
• You SHOULD commit your package-lock to source control
• As of npm ^5.1.x, package.json is now able to trump package-lock.json, so you should experience much less of a headache
• No more deleting that package-lock just to run `npm install` and regenerate it
• Use semver if your app offers an API, and adhere to the rules of semver.

Background

Semantic Versioning

Before you can understand the package-lock and even package.json, you have to understand semantic versioning (semver). It’s the genius behind npm, and what has made it more successful. You can read more about how npm uses it here. In a nutshell, if you are building an application with which other applications interface, you should communicate how the changes that you make will affect the third party’s ability to interact with your application. This is done via semantic versioning. A version is made up of three parts: X,Y,Z where those are major, minor and patch versions respectively. An example would be 1.2.3, or major version 1, minor version 2, patch 3. A change in patch represents a bugfix that doesn’t break anything. A change in minor version represents a new functionality that doesn’t break anything. A change in major version represents a large change that breaks compatibility. If users don’t adapt to a major version change, stuff won’t work.