简体中文 | English

Blazingly fast scanner to find and clean node_modules across your disks.

• Mode 1 (dir): Scan a specific directory (provide --path or input in the interactive menu).
• Mode 2 (all): Scan the entire machine (root on macOS/Linux; enumerate drives on Windows).
• Launching without arguments (including double-clicking the packaged binary) opens an interactive menu.

• Fast concurrent scanning (default concurrency: 64)
• Limit max recursion depth; toggle hidden directories
• Interactive confirmation and --dry-run preview to avoid accidental deletion
• Cross-platform (macOS / Linux / Windows)
• Packaged as standalone binaries you can double-click

cd /path/to/clean-node-modules
pnpm add -D pkg
pnpm run build
# Outputs dist/{clean-node-modules-*} binaries for each platform

# No arguments: open the interactive menu (1=dir, 2=all)
node bin/clean-node-modules.js

Interactive menu example:

Please choose:
1) Scan a specific directory
2) Scan the entire machine

# Mode 1: specific directory, delete without prompting
node bin/clean-node-modules.js --mode dir --path /path/to/projects --yes

# Mode 1: preview only (no deletion)
node bin/clean-node-modules.js --mode dir --path /path/to/projects --dry-run

# Mode 2: full disk scan (may be slow)
node bin/clean-node-modules.js --mode all

# Mode 2: scan user home only
node bin/clean-node-modules.js --mode all --path "$HOME"

# Mode 2: full disk scan and delete (dangerous)
node bin/clean-node-modules.js -m all -y
# Or explicitly set root path
node bin/clean-node-modules.js -m all -p / -y

Option	Description
`-m, --mode <dir	all>`
-p, --path <path>	Start path for dir mode; override start for all mode
-y, --yes	Delete without confirmation
-n, --dry-run	Preview node_modules to be deleted without deleting
-c, --concurrency <num>	Number of concurrent directory reads, default 64
-d, --max-depth <num>	Max recursion depth (0=top-level only), default Infinity
--include-dot	Include hidden directories (starting with .)
--exclude <a,b,c>	Comma-separated directory names to skip
-h, --help	Show help

• Base exclusions: .git, .hg, .svn, .cache, .idea, .DS_Store, dist, build, out, coverage, .pnpm-store, .npm, .yarn, .nvm, .cargo, .vscode, Pods, DerivedData, android, ios
• Extra for mode=all (macOS typical): Library, Applications, Movies, Music, Pictures, Public, Downloads, Desktop

You can add more via --exclude. Use --include-dot to include hidden directories.

• Full disk scanning can be slow. Prefer --path "$HOME" or a specific starting path when speed matters.
• Use --max-depth to limit traversal (e.g., --max-depth 2).
• Some system directories may be inaccessible; errors are safely ignored but cost time.

• macOS / Linux: mode=all defaults to root /.
• Windows: mode=all enumerates available drive letters (e.g., C:\\, D:\\).
• Packaged binaries can be double-clicked:

# macOS Apple Silicon
./dist/clean-node-modules-macos-arm64

# macOS Intel
./dist/clean-node-modules-macos-x64

• It's slow — what can I do?
  • Use --path "$HOME" or a narrower start path, or lower --max-depth.
• Risk of accidental deletion?
  • You will be prompted unless --yes is provided. Prefer a --dry-run first.
• Preview only?
  • Use --dry-run.

PRs are welcome!

git clone https://github.com/wangmiaozero/clean-node-modules.git
cd clean-node-modules
pnpm i
pnpm run build

Before submitting, please ensure:

• The code runs locally (both from source and as packaged binaries)
• README reflects the latest behavior

MIT © 2025 wangmiaozero

See LICENSE