What is Package Lock JSON (package-lock.json) file

Have you ever worked with Javascript? If you did, maybe you came across package-lock.json. What is package-lock JSON file? Why it is important? In this post, we address these questions, to better understand how to manage a Javascript project.

Not all projects have a package-lock.json

The truth is that this file is not present in all javascript projects. In fact, you may be writing JS code just fine without it. That’s often the case when you simply write inside a static page with <script> tags. However, that was the approach to javascript of early 2000. Fortunately, now things are completely different, and you may want to develop differently. In fact, modern applications have complex requirements, and you need a huge amount of javascript. Writing everything in a static page would be painful. Thus, developers started to modularize the code into packages. A package is a library, an amass of javascript code that does some things. When you develop an application, you want to use packages to avoid reinventing the wheel. You typically use the package in the way you need to achieve your goal.

One example can be Vue.js. Among other things, it takes care of relating the content of a text input to a variable. When the variable changes value, the text in the box changes value as well. And, of course, the other way around is also true. This way, you don’t have to waste your time implementing this functional code, but you can focus on your application logic.

Using code from other people means your application has some dependencies, and you need to manage them. A powerful tool to do it is the javascript package manager, npm. Now, if your code does have dependencies, that’s when the package-lock.json comes in.

What is package-lock.json?

Now that the preface is over we can get to the interesting part. What is package lock json file? In short, it is a file listing the full dependency tree of your project. What is the dependency tree? That’s even simpler. As said before, your project will depend on some packages, and you can find them in the package-lock.json. However, most likely, those packages will depend on other packages as well. Guess what, you can also find these in the file.

Besides the name of the packages, you also find the exact version you are using. This way, you can easily troubleshoot breaking changes, because you know which version you were using before. However, note that package-lock.json is just a snapshot. It does not contain history, so you need to use something to keep track of the version of this file. As a developer, the best option to do that is git.

When you install a new package with npm, its name and version automatically appear inside the package-lock.json file if you use the --save option. You may also install some packages that you want only in development mode, and not in production. The package-lock.json has room for that as well, and you can use the --save-dev option.

Having a file listing all the dependencies allows you to easily port your code from a machine to another.

Example package-lock.json

Now that we know what is package-lock.json, we can look at an example one. As you can guess by the name, it is a JSON file. Since a real package-lock.json file can be very long, we omit much of it.

{
    "requires": true,
    "lockfileVersion": 1,
    "dependencies": {
        "abbrev": {
            "version": "1.1.1",
            "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz",
            "integrity": "sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==",
            "dev": true
        },
        "accepts": {
            "version": "1.3.5",
            "resolved": "https://registry.npmjs.org/accepts/-/accepts-1.3.5.tgz",
            "integrity": "sha1-63d99gEXI6OxTopywIBcjoZ0a9I=",
            "dev": true,
            "requires": {
                "mime-types": "~2.1.18",
                "negotiator": "0.6.1"
            }
        }
  }
}

In this example, the file has just two dependencies, the abbrev and accepts packages. Respectively, we need them in version 1.1.1 and 1.3.5. Both of them are also to be included in development mode. Furthermore, the latter also requires mime-types and negotiator, that would be listed later in the real (long) file.

In Conclusion

In short, you will rarely have to edit a package-lock.json file manually. Nonetheless, it is important to understand what package lock json is, and why it is important. This will allow you to develop applications in a more predictable way. Let me know what you think of using the package-lock.json file in the comments.