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
Living in the root of your project right next to its big brother,
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 email@example.com /Users/david.lozzi/git/project ├─┬ @firstname.lastname@example.org │ └─┬ @email@example.com │ └─┬ @firstname.lastname@example.org │ └── email@example.com deduped └─┬ firstname.lastname@example.org └─┬ email@example.com └── firstname.lastname@example.org
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…
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:
js-cookieat version 2.2.1, always at that version
prop-typesat version 15.7.x, getting the latest patch version
reactat version 17.x.x, getting the latest minor and patch version
react-reduxwith 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.
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…
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
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
When should you use
npm install vs.
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.
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.
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.