CI Cache Cleaner

A CLI tool for cleaning npm cache that analyzes the dependency tree of the current project and removes unused cached content.

Introduction

In CI/CD environments, ~/.npm or specific cache directories are often cached to accelerate dependency installation. Over time, as package versions are updated, older versions of packages remain in the cache, causing the cache size to continuously expand, increasing storage costs and network transmission time.

CI Cache Cleaner uses @npmcli/arborist to analyze the complete dependency tree of the current project and compares it with the cached content to safely delete unused cache entries. It supports preserving package metadata cache, ensuring that necessary metadata information is retained during the cleanup process to meet the needs of projects that use --prefer-offline.

Differences from Other Solutions

Why not use lockfile as cache key?

Using lockfile as a cache key is certainly a good solution and is recommended under normal circumstances. However, using lockfile also has some problems:

1. Once the lockfile changes, the previous cache expires entirely, resulting in lower cache hit rates.
2. In enterprises, there may be many projects that do not use or fail to properly use lockfiles.

Why not use npm cache verify?

The npm cache verify command cannot clean up unused dependency caches in projects. It is mainly used to verify cache integrity and remove corrupted entries, but it does not identify and delete packages that are intact but no longer depended on by the project.

Why not use pnpm store prune?

When pnpm uses remote caching in CI environments, it causes pnpm store prune to be unable to accurately track which dependencies are still referenced, as symbolic links are broken during this process, affecting the accuracy of cache cleanup.

Limitations of Current Solution

1. Relies on the @npmcli/arborist library to analyze the dependency tree, which increases the complexity and number of dependencies of the project.
2. Requires a valid package-lock.json and node_modules directory in the project to accurately analyze dependencies.
3. For certain special package management scenarios (such as complex dependencies in monorepos), there may be cases of inaccurate analysis.
4. Due to the need to traverse the entire dependency tree and compare it with cached content, for large projects there may be longer execution times, requiring evaluation of efficiency comparisons with other solutions.
5. Only supports cache cleanup for the npm ecosystem and is not applicable to other package managers.

Installation

npm install -g @mod10/cicachecleaner

Usage

# Basic usage (using default cache path)
ccc

# Specify cache path
ccc -p /path/to/cache

# Specify project location
ccc -l /path/to/project

# Dry run mode (only show what will be deleted)
ccc --dry-run

# Skip confirmation prompt
ccc --force

# Show help
ccc --help

# Show version
ccc --version

Options

• -p, --path <path>: npm cache directory path (default: ~/.npm/_cacache)
• -l, --location <dir>: project location directory (default: current directory)
• -d, --dry-run: list what will be deleted without actually deleting
• -f, --force: skip confirmation prompt
• -h, --help: show help information
• -v, --version: show version information

Development

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Run Lint
npm run lint

# Link locally for CLI testing
npm link

License

MIT