why-slow

Diagnose why your Node.js project is slow — in seconds.

why-slow is a zero-config CLI tool that scans your project and gives you an instant performance report: large source files, oversized images, circular dependencies, and unused packages.

Installation

# Run instantly without installing
npx @saismrutiranjan18/why-slow

# Or install globally
npm install -g @saismrutiranjan18/why-slow

Usage

# Run in any project directory
why-slow

# Generate an HTML report
why-slow --html

# Show help
why-slow --help

What it checks

| Check | What it flags | |---|---| | Large Source Files | .js/.ts/.jsx/.tsx files over 200 KB | | Large Images | Images over 500 KB (png, jpg, webp, svg) | | Circular Dependencies | Modules that import each other in a loop | | Unused Dependencies | Packages in package.json not used in code | | node_modules Size | Total size of your installed dependencies |

Example Output

WHY-SLOW v1.1
────────────────────────────────────

i Largest Source Files
✓ No oversized source files found

i Image Analysis
! public/banner.png (1.2 MB)

i Circular Dependencies
✖ src/utils/format.js → src/helpers/date.js → src/utils/format.js

i Unused Dependencies
! lodash
! moment

i Dependencies
i node_modules size: 214.5 MB

────────────────────────────────────

Performance Summary

i Large Files: 0
i Large Images: 1
i Circular Dependencies: 1
i Unused Dependencies: 2

! Performance Score: 79/100

────────────────────────────────────

Scan completed successfully.

HTML Report

Run with --html to generate a performance-report.html file in your project root — a clean, shareable report with all findings.

why-slow --html

Performance Score

Your project gets a score out of 100:

| Issue | Penalty | |---|---| | Each large source file | −5 pts | | Each large image | −5 pts | | Each circular dependency | −10 pts | | Each unused dependency | −2 pts |

| Score | Rating | |---|---| | 90–100 | Great | | 70–89 | Needs attention | | 0–69 | Action required |

Requirements

• Node.js 18+

License

MIT © saismrutiranjan18