Npmfix

A Node.js CLI that fixes integrity check issues with NPM packages.

The problem

When:

• You link NPM packages a lot to speed up development
• Integration tests automatically install the package you’re developing from a local tarball (not yet published to the registry)

And then:

• A build server runs CI builds

You get:

• Integrity check failures in CI builds (error code EINTEGRITY).

Did you know? NPM makes sure that the checksum of a published package matches the checksum of the package you download (or fetch from your local cache) in order to avoid bad surprises after the installation.

The causes

In my case, these errors were caused by:

1. Different tarballs being installed: if we modify the source code of our package then the tarball we’ll build will probably have a different checksum, causing a mismatch with the one registered in package-lock.json. This kind of failures happen when installing packages in integration tests project.
2. Frequently linking/unlinking packages in several projects. Somehow this can mess with the checksums in package-lock.json files. This kind of failures come up when installing packages in your projects.

Solutions

You could solve these issues by disabling package-lock.json files, but this approach comes with downsides:

• You lose the guarantee that build servers and dev machines will install the same versions of packages.
• NPM will take more time to install dependencies because it won’t be able to skip metadata resolution anymore.

Integration tests projects don’t need these features, so it’s a good solution for the first kind of issues.

Did you know? Just pass the --no-package-lock flag when running npm i to prevent the generation of a package-lock.json file.

But what about the other kind of errors?

I was deleting package lock files and node_modules in each project presenting the error, sometimes even cleaning the global NPM cache. Then I reinstalled all the dependencies and pushed the resulting changes to the package-lock.json file. Now the triggered CI build would complete successfully.

But the whole process takes some time and I also felt like a human executing a script.

Automation

So I wrote a Node.js CLI tool to replace me in this tedious task. Npmfix is based on a very simple algorithm:

1. Continue only if the current folder has a package.json file.
2. Delete the node_modules folder.
3. Delete the package-lock.json file.

This functionality can be extended (e.g. recursive search, perform a global cache clean) by passing flags to the CLI.

More

If you want to know more about Npmfix and its usage, visit its Github repository.