npm cache

Anyone writing software today doesn’t build everything themselves. You download finished code building blocks made by other people and integrate them into your own program. For the programming language JavaScript, this usually happens via a tool called npm, which fetches such building blocks from a huge online archive. Every downloaded building block is additionally stored in a folder on the local hard drive. This folder is the npm cache. If a project later needs the same building block again, npm takes the copy from the disk instead of downloading it from the network again.

Why developers don’t want to download the same thing ten times

A single medium-sized JavaScript project quickly pulls in several hundred to over a thousand such building blocks. That’s because each building block brings along its own building blocks that it needs in turn. Without a cache, every installation would have to fetch all of that completely fresh from the internet. This costs minutes, uses up data volume, and puts unnecessary strain on the archive’s servers.

The effect becomes especially clear with automated test systems. Large companies have their software automatically rebuilt and tested several hundred times a day. Each of these runs installs the building blocks anew. A working cache can shorten such a run from several minutes to just a few seconds. Calculated over a month, that adds up to saved compute hours that someone would otherwise have to pay for.

There’s also the independence from the network. Anyone working on a train or in a café without a stable connection can still keep building a project thanks to the cache. The prerequisite is that the required building blocks have already been downloaded once before.

Checksums and the _cacache folder

The cache resides as a hidden folder in the personal user directory, under the name _cacache. Inside, the downloaded packages are not sorted by name but by a fingerprint of their content. This fingerprint is called a checksum: a long string of characters calculated from the content of the file. If even a single character in the package changes, an entirely different checksum results.

This has a practical advantage. npm can thus check whether a file from the cache is truly unchanged before incorporating it. If the checksum doesn’t match, the entry is discarded and downloaded again. You can picture this like a library in which every book is filed not by title but by a number calculated from the entire text.

A common misconception: the cache is not the same as the node_modules folder in the project. node_modules contains the building blocks that this one project is currently using. The cache is the shared stock for all projects on the machine. If you delete node_modules, reinstallation is still fast because the stock is still there.

From error forums to the supply-chain debate

Most commonly, the term is encountered in error messages and tutorials. When an installation fails for no apparent reason, a standard piece of advice is: clear the cache. The command for this is npm cache clean --force. It’s so well known that it has almost become a running joke in developer forums, even though it rarely fixes the actual underlying cause.

In trade news, the topic comes up in a larger context. When someone tampers with a popular package by inserting malicious code, this is referred to as a software supply chain attack. Caches play a dual role here: checksums make unnoticed tampering harder, while at the same time an already compromised copy can linger in the system longer than expected. For this reason, companies often operate their own cache servers for their entire team.

Anyone starting to program with JavaScript themselves notices the cache mainly through one detail. The first installation of a project takes noticeably long, the second one goes remarkably fast. That is precisely the cache at work.