Why Mole Clears Less npm Cache Than npm cache verify

A user recently said npm's cache was still there after a Mole maintenance pass, and that cleaning it themselves reduced it from 8 GB to 2 GB. That prompted another look at developer caches: which cached files are still needed, which have lost their references, and which tools already collect their own old data.

The investigation and changes described here were made on October 5. They are in the source for a future release; the published Preview package does not yet include them.

Why npm's cache keeps growing

npm's default cache is ~/.npm/_cacache. content-v2 stores packages and registry responses, while index-v5 maps requests to that content. Content files are named by hash, and several index entries can refer to the same file.

When package metadata changes, npm writes a new response. Later lookups can compact away older index entries without removing their content files, leaving files with no index reference. The npm documentation also says the cache does not remove data by itself and grows as packages are installed.

The user had already cleaned their cache, so I had no copy from before the cleanup and could not confirm the exact command they ran. The 8 GB to 2 GB report started this investigation; it is not a measurement of Mole reclaiming 6 GB, or proof that all 6 GB had no references.

What verify removed in this test

The experiment used copies of my Mac's cache with npm 11.19.1 and cacache 20.0.4. The original was unchanged. It was about a day old, with 309796162 bytes of content, rather than a cache accumulated over several months.

The difference comes from cacache's verify implementation. It collects content, checks integrity and rebuilds the index, keeping the last entry for each key. Earlier entries can still contain full and abbreviated metadata used by different requests; those are not simply old and new copies of one response.

On the copy, 11199796 bytes removed by verify were still referenced by valid entries for another request variant. Some package information that could be read offline before verification returned ENOTCACHED from offline npm view afterward. It could be fetched again online, but the cache's behavior had changed.

Mole takes the narrower rule: any valid index entry keeps its content. Finding only about 0.6 MB in this sample is preferable to evicting a usable variant just to approach verify's result.

Clearing unused files without clearing the whole cache

The new implementation scans only the default ~/.npm/_cacache. Unreferenced content older than a day appears as one default-selected row in Clean's developer section. Removing the whole npm cache still requires review, and overlapping selections count their bytes once.

Mole leaves these files alone while commands such as npm install or npm ci are writing to the cache. If the index cannot be read, the files are not offered for cleanup. References are checked again before deletion; index files and temporary directories are left alone. Mole does not run npm's cleanup command in the background.

Preserving index references does not guarantee every project can always build offline. A lockfile can request a tarball directly by hash, and private registries or old versions may not remain available. Source files, lockfiles and any build output that cannot be recreated still need to be kept separately. Custom npm cache locations are outside this change.

Go, Cargo and pnpm need different decisions

Go already trims its build cache. Its implementation keeps entries used within five days plus a one-hour margin, or 121 hours. Mole previously offered the entire build-cache directory for default cleanup; this change narrows that to the same age rule, keeping recent entries that would otherwise have to be rebuilt.

Cargo already has automatic cache collection, and nothing in this sample was due for it. An earlier removal of extracted registry sources was followed about 29 hours later by roughly 157 MB of downloads and 1.06 GB of unpacking. Mole adds no separate automatic collector for that store; its existing review-only cleanup rows remain available.

pnpm's shared store is different again. In the APFS sample, hard-link counts could not prove content unused; copying that criterion would select the whole store. No new pnpm collector was added. The hard-link count would need to show whether a file is still in use on that filesystem before Mole could use it for cleanup.

Build output inside global tools and old Xcode projects

The globally installed pake-cli contained a src-tauri/target folder of about 1.48 GiB: Rust output from building its Tauri shell, rather than npm's download cache. Such build folders carrying a valid tool-written CACHEDIR.TAG are now offered for review. Mole keeps the installed tool and its node_modules dependencies, and does not offer these folders while a Rust build is running.

The survey also found 24 Xcode DerivedData folders, about 9 GiB, whose recorded project paths no longer existed. A whole folder is offered only when the project is confirmed missing on the startup disk and Xcode has not used the corresponding cache for at least two weeks. An absent external drive or denied read permission does not establish a missing project. These are findings from that survey, not promised savings on every Mac; rebuilding still takes time if the output is needed again.

Check which layer you are cleaning

This read-only command asks npm for its actual cache location, including a configured custom path.

npm config get cache

Once installs and builds have stopped writing to that cache, decide whether to run npm cache verify. It changes the cache; it is not an inspection-only command. Project node_modules folders and globally installed commands are separate layers that it does not clean. The developer-cache guide covers the wider workflow.