clearnpmod/README.md

A CLI tool to find and clean up node_modules directories recursively

# 🧹 clearnpmod

[![npm version](https://badge.fury.io/js/clearnpmod.svg)](https://badge.fury.io/js/clearnpmod)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)](https://nodejs.org/)

A powerful and interactive CLI tool to find and clean up `node_modules` directories recursively. Perfect for freeing up disk space by removing unused dependencies across multiple projects.

## ✨ Features

- 🔍 **Recursive scanning** - Finds all `node_modules` folders in a directory tree
- ✅ **Interactive selection** - Checkbox interface to choose which folders to delete
- 🛡️ **Safe by default** - All folders are pre-selected, but you confirm before deletion
- ⚡ **Fast scanning** - Efficiently traverses directory structures
- 📊 **Clear feedback** - Shows progress and results with emojis
- 🚫 **Permission handling** - Gracefully skips inaccessible directories

## 📦 Installation

### Global Installation (Recommended)

```bash
npm install -g clearnpmod
```

Or with pnpm:

```bash
pnpm add -g clearnpmod
```

### One-time Usage (npx)

```bash
npx clearnpmod <path>
```

## 🚀 Usage

### Basic Usage

```bash
clearnpmod /path/to/your/projects
```

### Examples

```bash
# Clean current directory
clearnpmod .

# Clean your entire projects folder
clearnpmod ~/Development

# Clean a specific project
clearnpmod /Users/username/my-project
```

### Interactive Demo

```
$ clearnpmod ~/Development

Scanning for node_modules folders under:
  /Users/username/Development
(This may take a moment...)

? Select which node_modules directories you want to delete: (Press <space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
❯◉ /Users/username/Development/project1/node_modules
 ◉ /Users/username/Development/project2/node_modules
 ◉ /Users/username/Development/old-project/node_modules

Deleting 3 folder(s)...
✅ Deleted: /Users/username/Development/project1/node_modules
✅ Deleted: /Users/username/Development/project2/node_modules
✅ Deleted: /Users/username/Development/old-project/node_modules

Done.
```

## 🎯 Use Cases

- **Free up disk space** - `node_modules` can take up gigabytes of space
- **Clean old projects** - Remove dependencies from projects you're no longer working on
- **Prepare for backup** - Clean up before backing up your development folder
- **System maintenance** - Regular cleanup of your development environment

## ⚠️ Important Notes

- **Backup important projects** - Make sure you can reinstall dependencies with `npm install` or `pnpm install`
- **Git repositories** - Your source code is safe; only `node_modules` folders are affected
- **Active projects** - Avoid deleting `node_modules` from projects you're currently working on

## 🛠️ Requirements

- Node.js >= 14.0.0
- Works on macOS, Linux, and Windows

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

### Development Setup

1. Clone the repository
2. Install dependencies: `pnpm install`
3. Test locally: `node clearnpmod.js <test-path>`

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🐛 Issues

If you encounter any problems or have suggestions, please [open an issue](https://github.com/K4Lok/clearnpmod/issues).

## 📚 Related Tools

- [npkill](https://www.npmjs.com/package/npkill) - Alternative with a different interface
- [rimraf](https://www.npmjs.com/package/rimraf) - For programmatic deletion
- [du](https://linux.die.net/man/1/du) - Unix command to check disk usage

---

Made with ❤️ for the JavaScript community