This is great when you are building an application like a web application or server because in a CI environment we want to emulate the behavior of the user. So if we start tracking our lock file in our source control (like git), we can make sure that every developer as well as the server or build system and our CI system uses the very same versions of dependencies.

So why wouldn't we want to do the same thing when we author libraries or other things meant to be published to the npm registry? In order to answer this, we'll first have to talk about how publishing works.

How Publishing a Module Works

Contrary to what some people believe, the content that you publish to npm is not always the same as what's on GitHub or overall in your project. The way that a module is published is that npm will determine the files that should be published by checking for a files key in your package.json and a .npmignore file or if none is present the .gitignore file. There are also some files that are always included and some that will always be excluded. You can find the entire list of those files on the npm page. For example the .git folder will always be ignored.

Afterwards npm will take the list of files and will package them all up together into a tarball using npm pack . If you want to check out what files are packaged you can run in a project npm pack --dry-run and you'll an output with all of the files:

That tarball will then be uploaded to the npm registry. One thing you might notice when you run this command is that if you already have a package-lock.json it is actually not being bundled. This is because package-lock.json will always be ignored as specified by the list in the npm docs.

Subsequently this means that if another developer installs your published package, they'll never download your package-lock.json and therefore it will be completely ignored during the installation.

This might cause the "works on my machine" effect by accident since your CI and developer environment might pick up a different version of dependencies than your users. So what can we do instead?

Disabling Lock Files and Shrinkwrapping