🧹 Node-Janitor

Smart CLI tool to clean up node_modules folders - free up disk space automatically

✨ Features

• 🔍 Smart Scanner - Find all node_modules in your system
• ⏰ Time-based Cleanup - Delete folders older than X days
• 🧼 Deep Clean - Remove unnecessary files (docs, tests, source maps)
• 👁️ Dry Run - Preview before deleting
• 🎮 Interactive Mode - Step-by-step wizard
• 💾 Backup - Save list before deletion
• 📊 Reports - Detailed analytics
• ⚡ Fast Mode - Native OS commands for speed
• 🔄 CI/CD Ready - Silent mode with JSON output
• ⚙️ Config File - Persistent settings with .janitorrc
• 🔀 Git-aware - Skip repos with uncommitted changes
• 🌍 Multi-language - 8 languages supported
• 👀 Watch Mode - Continuous monitoring
• 📅 Scheduled Cleanup - Cron-style automation

📦 Installation

# Global installation
npm install -g node-janitor

# Or use with npx
npx node-janitor

🚀 Quick Start

# Scan current directory
node-janitor

# Scan specific path
node-janitor --path ~/projects

# Preview what would be deleted (dry run)
node-janitor --path ~/projects --dry-run

# Delete folders older than 30 days
node-janitor --older-than 30d

# Interactive mode
node-janitor --interactive

🖥️ Interactive TUI Mode (NEW!)

Launch a full-screen, keyboard-navigable interface similar to npkill:

# Start TUI mode
node-janitor --live

# Or use the tui subcommand
node-janitor tui --path ~/projects

Features:

• ⌨️ Keyboard Navigation - Use arrow keys or j/k to navigate
• ☑️ Multi-select - Press SPACE to select/deselect folders
• 🔄 Sort toggle - Press S to switch between size/age sorting
• 🎨 Color-coded - Green (new), Yellow (medium), Red (old)
• 🗑️ Quick delete - Press D to delete selected folders
• 📊 Real-time stats - See total size and selection count

┌──────────────────────────────────────────────────────────────────┐
│  🧹 NODE JANITOR - Interactive Mode                               │
├──────────────────────────────────────────────────────────────────┤
│  📊 Found: 15 folders | Total: 2.5 GB | Selected: 3 (523 MB)     │
├──────────────────────────────────────────────────────────────────┤
│  > ■ ~/projects/old-app/node_modules          523 MB    180 days │
│    □ ~/projects/test-project/node_modules     312 MB     95 days │
│    ■ ~/projects/archived/node_modules         245 MB     45 days │
│    □ ~/projects/client-work/node_modules      198 MB     30 days │
├──────────────────────────────────────────────────────────────────┤
│  [↑/↓] Navigate  [SPACE] Select  [A] All  [S] Sort  [D] Delete   │
└──────────────────────────────────────────────────────────────────┘

📖 Usage

Basic Commands

# Scan and show all node_modules
node-janitor --path ~/projects

# Limit scan depth
node-janitor --path ~/projects --depth 3

# Quick scan (skip size calculation)
node-janitor --path ~/projects --quick

Time-based Cleanup

# Delete folders older than 30 days
node-janitor --older-than 30d

# Delete folders older than 3 months
node-janitor --older-than 3m

# Delete folders between 30-90 days old
node-janitor --between 30d-90d

Size Filters

# Only delete folders larger than 500MB
node-janitor --min-size 500MB

# Only delete folders smaller than 10MB
node-janitor --max-size 10MB

Deep Clean Mode

Remove unnecessary files from node_modules without deleting the entire folder:

node-janitor --deep-clean

Files removed:

• Documentation: *.md, LICENSE, CHANGELOG, docs/
• Tests: test/, tests/, __tests__/, spec/
• Source maps: *.map
• Examples: example/, examples/
• Config files: .eslintrc, .prettierrc, etc.

Safe Mode

# Preview without deleting
node-janitor --dry-run

# Create backup before deletion
node-janitor --backup

# Only delete if lockfile exists
node-janitor --lock-check

Performance

# Use native OS commands (faster)
node-janitor --fast

# Parallel deletion
node-janitor --parallel 4

Reports

# Generate report
node-janitor report

# Detailed report
node-janitor report --detailed

# JSON output
node-janitor report --json

CI/CD Integration

# Silent mode (no prompts, no colors)
node-janitor --silent --older-than 30d

# JSON output for automation
node-janitor --json

Exclude Patterns

# Exclude specific folders
node-janitor --exclude "important-project,client-work"

# Include only matching patterns (whitelist)
node-janitor --include "work-*,client-*"

Git-aware Cleanup

# Skip repos with uncommitted changes
node-janitor --skip-dirty-git

# Only process folders inside git repos
node-janitor --git-only

Config File

Create .janitorrc in your home directory or project:

{
  "exclude": ["important-project"],
  "defaultOlderThan": "30d",
  "defaultPath": "~/projects",
  "lang": "vi"
}

Use custom config:

node-janitor --config ~/.my-janitor-config.json

Multi-language Support

# Vietnamese
node-janitor --lang vi

# Chinese
node-janitor --lang zh

# Japanese  
node-janitor --lang ja

# Available: en, vi, zh, ja, ko, es, fr, de

Watch Mode

Continuously monitor and clean:

# Watch with 60s interval
node-janitor watch --interval 60 --older-than 30d

# Auto-clean when found
node-janitor watch --auto-clean --older-than 60d

Scheduled Cleanup

Cron-style scheduling:

# Daily cleanup at midnight
node-janitor schedule --daily --older-than 30d

# Weekly on Sunday
node-janitor schedule --weekly

# Custom cron expression
node-janitor schedule --cron "0 0 * * *" --older-than 60d

📋 All Options

| Option | Description | |--------|-------------| | -p, --path <path> | Directory to scan (default: current) | | -d, --depth <n> | Maximum scan depth | | --older-than <duration> | Only process folders older than (30d, 3m, 1y) | | --between <range> | Age range (30d-90d) | | --min-size <size> | Minimum folder size (500MB) | | --max-size <size> | Maximum folder size (10MB) | | --dry-run | Preview only | | --deep-clean | Remove unnecessary files | | --fast | Use native OS commands | | --parallel <n> | Number of parallel deletions | | --backup | Create backup before deletion | | --lock-check | Only delete if lockfile exists | | --quick | Skip size calculation | | -i, --interactive | Interactive mode | | -v, --verbose | Verbose output | | --debug | Debug mode | | --silent | Silent mode (CI/CD) | | --json | JSON output | | --exclude <patterns> | Exclude patterns (comma-separated) | | --include <patterns> | Include only matching patterns | | -c, --config <path> | Config file path | | --skip-dirty-git | Skip repos with uncommitted changes | | --git-only | Only process git repos | | --lang <code> | Language (en, vi, zh, ja, ko, es, fr, de) |

🎯 Examples

Clean old projects

# Find and delete node_modules older than 90 days
node-janitor --path ~/projects --older-than 90d

Deep clean to save space

# Remove docs, tests, source maps from all node_modules
node-janitor --path ~/projects --deep-clean

CI/CD cleanup

# Automated cleanup in CI
node-janitor --silent --older-than 60d --json

Cautious cleanup

# Preview first
node-janitor --path ~/projects --older-than 30d --dry-run

# Then execute with backup
node-janitor --path ~/projects --older-than 30d --backup

📊 Sample Output

🧹 NODE JANITOR

✔ Found 15 node_modules folders

┌─────┬──────────────────────────────┬──────────┬───────┬──────────┬──────┐
│ #   │ Path                         │ Size     │ Age   │ Packages │ Lock │
├─────┼──────────────────────────────┼──────────┼───────┼──────────┼──────┤
│ 1   │ ~/projects/old-app           │ 523 MB   │ 180d  │ 1,234    │ npm  │
│ 2   │ ~/projects/test-project      │ 312 MB   │ 95d   │ 567      │ yarn │
│ 3   │ ~/projects/archived          │ 245 MB   │ 45d   │ 890      │ npm  │
└─────┴──────────────────────────────┴──────────┴───────┴──────────┴──────┘

┌───────────────┬──────────┐
│ Total Folders │ 15       │
│ Total Size    │ 2.5 GB   │
│ Oldest        │ 180 days │
│ Newest        │ 5 days   │
└───────────────┴──────────┘

🔧 Development

# Clone repository
git clone https://github.com/patchybean/node-janitor.git
cd node-janitor

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/index.js --help

📄 License

MIT © Patchy Bean

Made with ❤️ for developers who hate bloated disk space