npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

junkdoctor

v1.0.1

Published

Find and safely clean node_modules, .next, venv, dist, and other project junk folders

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

foisalfoisal

Keywords

junkdoctorcleanupdisk-usagenode_modulesvenvnextjsclituideveloper-toolscache

Readme

JunkDoctor

Your smart project junk cleaner.

JunkDoctor finds heavy folders developers usually delete — node_modules, .next, venv, dist, caches, and more — measures disk use, and helps you safely clean them from the CLI or an interactive menu.

Repository: github.com/foisalislambd/JunkDoctor

Node License TypeScript

Table of contents

Features

| Feature | Description | |---------|-------------| | Multi-target scan | Finds node_modules, .next, venv, dist, caches, and more | | Disk analysis | Async size measurement for every junk type | | One-shot clean | clean --everything removes all supported junk safely | | Path scope | clean --in <folder> only cleans inside a chosen directory | | Safety layer | Risk levels (LOW / MEDIUM / HIGH), blocked system paths | | Dry-run | Preview destructive actions without changes | | Interactive TUI | Menu with scan, browse, and clean shortcuts | | Fast scanning | fdir + bounded parallel I/O |

Install

From npm

npm install -g junkdoctor

After install, run junkdoctor or jd in your terminal.

From source

git clone https://github.com/foisalislambd/JunkDoctor.git
cd JunkDoctor
npm install
npm run build
npm link

After linking, run junkdoctor or jd (same as the global install).

Quick start

Easiest path: open the menu and pick what you need.

junkdoctor

You get a simple menu:

  1. Find my projects — scan for junk folders
  2. Browse all projects — list + quick actions
  3. Show biggest folders — what eats the most disk
  4. Clean old node_modules — idle 90+ days
  5. Clean old .next / Python envs
  6. Clean ALL junk types — one place for everything
# Or use short CLI commands
junkdoctor doctor                              # scan + tips
junkdoctor scan                                # find projects + junk
junkdoctor targets                             # list cleanable folder types
junkdoctor biggest                             # top disk users
junkdoctor clean --everything --dry-run        # preview: all junk types
junkdoctor clean --target node_modules --all   # only node_modules everywhere
junkdoctor clean --target venv --all           # only Python venvs
junkdoctor clean --target python --all         # venv + __pycache__
junkdoctor clean --in D:\work --everything --dry-run   # only inside a folder
junkdoctor clean --next --stale                # idle .next caches
junkdoctor reinstall ./my-app                  # fresh Node install

Tip: always try --dry-run before a real clean.

CLI reference

Default command

Running junkdoctor with no subcommand opens the interactive TUI.

Commands

| Command | Description | |---------|-------------| | scan [paths...] | Discover projects and measure all junk folders | | analyze | Health summary from cached scan | | biggest | List largest projects by total junk size | | clean | Remove junk folders with safety checks | | targets | List supported cleanable folder types | | reinstall <path> | Delete node_modules and reinstall dependencies | | doctor | Quick scan + recommendations | | ui / tui | Open interactive terminal UI | | cache-path | Show where scan cache is stored | | clear-cache | Clear the saved scan cache | | --help | Show help | | --version | Show version |

scan options

| Flag | Description | |------|-------------| | --all | Include current directory + all default home dev roots |

Examples:

junkdoctor scan
junkdoctor scan ~/projects
junkdoctor scan --all

biggest options

| Flag | Description | |------|-------------| | -n, --limit <number> | Number of projects to show (default: 20) |

clean options

| Flag | Description | |------|-------------| | --dry-run | Preview only — nothing deleted | | --force | Skip LOW/MEDIUM confirmations (HIGH still requires typing DELETE) | | --stale | Only caches not modified in 90+ days | | --min-mb <n> | Minimum size in MB (still excludes global and HIGH-risk) | | --all | All eligible non-global, non-high-risk matches | | --everything | Clean every supported junk type | | --target <list> | Types: node_modules, next, venv, python, dist, all, … | | --next | Alias for --target next | | --in <path> | Only clean inside this folder (scans it first) |

Default behavior (no flags): stale node_modules, non-global, non-high-risk only.

Supported targets: node_modules, next, venv (venv/.venv/env), pycache, dist/build, .turbo, .cache/.parcel-cache, coverage, .nuxt/.output, target (Rust). Aliases: python → venv+pycache, all → everything.

Global and high-risk folders are never included in bulk clean.

Global packages (separate):

junkdoctor clean --global --dry-run   # preview other global packages
junkdoctor clean --global             # remove them (junkdoctor stays)

The whole global node_modules folder is never deleted. junkdoctor itself is always protected.

Examples:

junkdoctor clean --everything --dry-run
junkdoctor clean --target node_modules --all
junkdoctor clean --target venv,dist --all --dry-run
junkdoctor clean --target python --all
junkdoctor clean --in D:\work --everything --dry-run
junkdoctor clean --in ~/projects --target node_modules --all
junkdoctor clean --next --stale
junkdoctor clean --min-mb 500 --target next --all

reinstall options

| Flag | Description | |------|-------------| | --dry-run | Preview only | | --force | Skip confirmations |

junkdoctor reinstall C:\path\to\project
junkdoctor reinstall ./my-app --dry-run

Interactive UI (TUI)

Launch:

junkdoctor
# or
junkdoctor ui

Main menu (start here)

Everything important is one pick away:

| Menu item | What it does | |-----------|----------------| | Find / Scan again | Discover projects and measure sizes | | Browse all projects | Scroll list + quick keys | | Show biggest folders | Top space users | | Clean old node_modules | Idle packages (90+ days) | | Clean old .next caches | Idle Next.js build caches | | Clean old Python envs | Idle venv / pycache | | Clean ALL junk types | Every supported folder type | | Clean global npm packages | Other global packages only — junkdoctor never removed |

Project list shortcuts

| Key | Action | |-----|--------| | ↑ / ↓ or j / k | Move selection | | A | Clean ALL junk folders on the current list/page | | D | Delete node_modules for selected project | | N | Delete .next for selected project | | I | Reinstall dependencies | | V | View details | | Enter / Space | Full action menu (includes Clean ALL for that project) | | / | Search by name or path | | R | Rescan | | H / Esc | Back to main menu | | Q | Quit |

On clean pages (node_modules / .next / venv / everything), the top menu item is Clean ALL on this page, or press A.

Bulk clean wizard

Clean ALL opens a step-by-step flow:

  1. Review — projects, folders, space to free, type breakdown, biggest targets
  2. Preview only (recommended) — nothing deleted
  3. Clean all now — progress 7 of 12, then a Finished summary

Global and high-risk folders are never included.

On single-project confirm: choose Preview only first if you are unsure — nothing is deleted.

Safety system

JunkDoctor is built to prevent accidents.

| Risk | Behavior | |------|----------| | LOW | Standard yes/no confirmation (CLI) | | MEDIUM | Confirmation + warnings (outside home, large cache, etc.) | | HIGH | Must type DELETE to confirm; global node_modules blocked; excluded from bulk clean |

Automatically blocked

  • Windows: Windows, System32, Program Files, etc.
  • Global / system node_modules — hard-blocked (cannot delete or reinstall), including %APPDATA%\npm\node_modules and packages inside it
  • System root drives

--force skips LOW/MEDIUM prompts only — HIGH-risk actions still require typing DELETE. Global node_modules stays blocked even with --force.

Always preview first

junkdoctor clean --dry-run
junkdoctor reinstall ./app --dry-run

How scanning works

By default, junkdoctor scans common folders under your home directory:

Desktop, Documents, Projects, code, GitHub, dev, and similar paths (see src/utils/paths.ts).

For each package.json found (skipping nested node_modules):

  1. Detect package manager from lockfiles
  2. Measure node_modules size (if present)
  3. Measure .next size (if present — Next.js)
  4. Assign risk score
  5. Cache results locally (junkdoctor cache-path)
junkdoctor scan --all   # Also scan cwd + all default roots

Development

git clone https://github.com/foisalislambd/JunkDoctor.git
cd JunkDoctor
npm install

| Script | Description | |--------|-------------| | npm run build | Compile TypeScript to dist/ | | npm start | Run CLI (node dist/cli.js) | | npm run dev | Watch + rebuild + launch TUI | | npm run build:watch | Watch + rebuild only | | npm run typecheck | TypeScript check without emit |

Architecture

src/
├── cli.ts                 # CLI entry (commander)
├── cli/commands/          # scan, analyze, clean, doctor, …
├── cli/display.ts         # Terminal tables & summaries
├── core/
│   ├── scanner.ts         # Filesystem crawl
│   ├── project-meta.ts    # Per-project metadata + risk
│   ├── analyzer.ts        # Health summaries
│   ├── disk-usage.ts      # Async directory sizing
│   ├── package-manager.ts # npm/yarn/pnpm/bun
│   └── global-prefix.ts   # Global npm path
├── safety/                # Path guard + confirmations
├── services/
│   ├── actions.ts         # Delete / reinstall single project
│   └── bulk-clean.ts      # Bulk plan + execute (CLI + TUI)
├── store/cache.ts         # Scan persistence (conf)
└── tui/                   # Ink React terminal UI
    ├── App.tsx
    └── components/

Requirements

  • Node.js 18+
  • npm (for global prefix detection; projects may use yarn/pnpm/bun)

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for setup, PR checklist, and guidelines.

Please follow the Code of Conduct. Security issues: see SECURITY.md.

Open an issue

License

MIT