npm install and the package-lock.json file

There’s something that lives in many modern development projects, sleeping quietly in the root of the project, this little file package-lock.json. Most of us treat it with discontent, and ignore it completely, or at best, delete it every once in a while cause some stack overflow or blog post told us to. There are about 57,000 pages on Google that talk about deleting package-lock.json. Why does that work and what does it do? If we can just delete it, why even have it?

What is the package-lock.json file?

Living in the root of your project right next to its big brother, package.json, is package-lock.json. This is a file that npm creates and updates automatically every time you run npm install (or npm i). It tracks the exact versions of packages and their dependencies that are installed in your project. Go take a peek at yours. You’ll see every library and package, every one, listed there. You’ll see some you didn’t install. The package-lock.json file tracks every package your app uses, and packages your packages use, all the way down the tree!

If you’re curious to see who’s using a specific package, try npm list packagename and it’ll list the tree for that package.

npm list js-tokens

project@1.0.0 /Users/david.lozzi/git/project
├─┬ @babel/core@7.21.4
│ └─┬ @babel/code-frame@7.21.4
│   └─┬ @babel/highlight@7.18.6
│     └── js-tokens@4.0.0  deduped
└─┬ prop-types@15.8.1
  └─┬ loose-envify@1.4.0
    └── js-tokens@4.0.0 

The package-lock.json file ensures that everyone working on the project has the same versions of packages, which is crucial for avoiding conflicts and unexpected behavior. This should remove some of the “it works on my machine” when our test or production environments act differently.

If you’re wondering, yes, this file is important and should be kept, and included in your code repository. Make sure this is under version control with the rest of your project files. Should we delete it? Read on…

Using npm install

As you know, npm i is used to install packages from the Node Package Manager (npm). When you run npm i <package-name>, npm downloads the package from the registry and installs it in your project’s node_modules directory. (this folder should not be version controlled, make sure it’s in your .gitignore file, and especially not synced with the cloud, like through OneDrive. I did that once, and it hurt… a lot.)

After the package is downloaded, the package-lock.json file is then updated with the exact version that was downloaded. Why? Well, your package.json (yea, with no lock) doesn’t always track the exact version of a package. Take this example:

    "js-cookie": "2.2.1",
    "prop-types": "~15.7.2",
    "react": "^17.0.0",
    "react-redux": ">=8.0.0",

What this will do:

• Install js-cookie at version 2.2.1, always at that version
• Install prop-types at version 15.7.x, getting the latest patch version
• Install react at version 17.x.x, getting the latest minor and patch version
• Install react-redux with the latest version that’s greater than or equal to version 8.0.0

As you may surmise if a team of developers did their own npm install at varying times, they could all get different versions! And with each of them running npm install, they’re all updating the package-lock.json file, and now the others have to npm i to match versions (and may inadvertently update package-lock.json again). It can be a vicious cycle…

In your local development environments, this is actually okay. You want to work with the latest libraries, and if you really don’t, then change your package.json file to limit the versions. Npm uses the ^ prefix on versions as a default, allowing minor versions through. Edit your package accordingly to limit the version. I don’t suggest forcing them all to be a specific version by removing the prefix. Getting most patches and minor versions is a good thing: folks managing these packages will release fixes, security patches, etc. that will improve your app. You’ll get the latest version the next time you do an npm i. According to best practices of using version numbering (see semver), patches and minor updates should not cause breaks… in theory.

It’s also worth noting that when you do an npm i with a package-lock.json file, the install process does refer to the lock file to check versions (among other things). If the packages and versions listed in the package-lock.json file match the dependencies specified in the package.json file, npm will simply install those packages without making any changes.

You may want to delete the package-lock.json file, if needed, to clear npm’s head a little, and let it go out to the wild and get everything it needs. If you do delete it, make sure to do an npm i right after to recreate it. Keep in mind, that lock file will now have all of the latest packages (per the version defined in package.json). Again, this should be okay and is recommended. Make sure you keep that lock file in your repo, ’cause you’ll need it for the next part.

What is npm ci?

Given the above, you might start wondering “Why have a package-lock.json file to begin with? It’s always being updated and I can just delete it!”. I’d agree. Why bother? There must be a way to rely on this file to guarantee the same versions will be installed again and again…

Enter npm ci!

npm ci is a more strict and reliable version of npm install. I’m not entirely sure what ci stands for, many think it stands for Continuous Integration. This isn’t a terrible definition as npm ci is designed to be used in your automation, test, build, and/or deployment pipelines. The primary difference between npm ci and npm install is that npm ci requires an existing package-lock.json file and installs the exact versions of packages specified in that file.

npm install will refer to and update package-lock.json as needed.

npm ci will rely on the package-lock file to determine which versions to install. It will not update the package-lock.json file.

Pretty straightforward. Also, because it’s reading the lock file, npm ci tends to be faster, there’s no discovery or negotiating on what version to pull, it just reads the file. I saw a 60-80s install in my pipeline drop to about 20-30s after switching to npm ci.

When should you use npm install vs. npm ci?

I recommend using npm install during development when you are actively working on the project and installing new packages. Your dev team should always use npm install. Make sure package-lock.json is in your code repo.

Use npm ci in your automation and build pipelines to ensure that the exact same versions of packages are installed in every environment. This will guarantee consistency and removes the possibility of version conflicts or unexpected behavior. Also, it’ll speed up your pipeline a little bit too.

npm install for developers.

npm ci for pipelines.

Good? Good.

What did I miss? Any tips you’d suggest for using npm and dealing with the package files, versions, etc? Leave a comment below!

Subscribe to my blog and get posts like this in your inbox. Share your email below, or follow me on Twitter.