👻🚫 BloatBuster

Find and remove unused dependencies from your Node.js projects. BloatBuster scans your project, identifies bloat, and provides a beautiful dashboard to help you clean up your package.json.

Quick Start

Install

npm install -g bloatbuster

Or use it without installing:

npx bloatbuster

Use

Navigate to your project directory and run:

cd /path/to/your-project
bloatbuster

The dashboard will open automatically in your browser! 🎉

What BloatBuster Does

BloatBuster analyzes your Node.js project and:

• 🔍 Finds unused dependencies - Detects packages that aren't actually used in your code
• 📦 Shows package sizes - See how much space each dependency takes (including transitive dependencies)
• 🧬 Explains dependencies - Understand why each package is installed and what depends on it
• 💡 Suggests alternatives - Get recommendations for lighter alternatives to heavy packages
• ✂️ Optimizes imports - Get hints on how to improve tree-shaking and reduce bundle size
• 🧨 Safe removal - Remove unused packages with automatic rollback if something breaks

Usage

Basic Scan

bloatbuster

Scans your current directory and opens the dashboard.

Include Dev Dependencies

bloatbuster --include-dev

Also analyzes packages in devDependencies.

Custom Port

bloatbuster --port 4000

Use a specific port for the dashboard (default is random 3000+).

Combine Options

npx bloatbuster --include-dev --port 4000

Dashboard Features

When you run BloatBuster, a web dashboard opens showing:

For Each Dependency

• Status Badge - UNUSED, LARGE, or OPTIMAL
• Size Information - Self size and total size (including all transitive dependencies)
• Dependency Chain - See which packages require this one
• Unused Explanations - If unused, understand why (e.g., only used in scripts, installed transitively, etc.)
• Impact Level - low, medium, or high based on size
• Lighter Alternatives - Suggestions for smaller replacement packages when available
• Import Optimization - Hints on how to improve tree-shaking (e.g., use lodash/map instead of import _ from 'lodash')
• File References - See exactly where the package is used in your code

Actions

• Remove - Remove a single unused dependency
• Remove All Unused - Bulk remove all unused packages
• Safe Purge - Remove with automatic validation and rollback (runs your tests/build to ensure nothing breaks)

How It Works

1. Scans your project - Reads package.json and analyzes your codebase
2. Detects unused packages - Uses advanced analysis to find packages that aren't imported or used
3. Builds dependency tree - Maps out which packages depend on which
4. Calculates sizes - Measures disk space used by each package
5. Opens dashboard - Launches a local web server with interactive visualization

Safe Removal

BloatBuster's Safe Purge feature:

1. Removes the dependency
2. Re-scans your project
3. Runs your tests (if you have a test script) or build (if you have a build script)
4. Automatically rolls back if validation fails
5. Reports how much space you saved

This ensures you can safely remove dependencies without breaking your project.

Examples

Find unused packages

cd my-project
bloatbuster

Analyze everything including dev dependencies

bloatbuster --include-dev

Use a specific port

bloatbuster --port 8080

Troubleshooting

"Web build not found" error

If you see this error, try:

npm uninstall -g bloatbuster
npm install -g bloatbuster

This will reinstall BloatBuster with the pre-built web dashboard.

Dashboard doesn't open

The dashboard runs on http://localhost:[port]. Check the terminal output for the exact URL and open it manually in your browser.

Port already in use

Use the --port option to specify a different port:

bloatbuster --port 4000

Requirements

• Node.js 14+
• npm, yarn, or pnpm
• A Node.js project with a package.json file

License

MIT