why-slow

A zero-configuration Node.js CLI that observes your app at runtime, detects common performance bottlenecks, and explains why your backend is slow in plain language.

Install

npm install why-slow

Or run without installing:

npx why-slow node your-app.js

Usage

why-slow <command> [args...]

Examples:

why-slow node server.js
why-slow node index.js
npx why-slow node examples/slow-app.js

Your app runs as usual; when it exits, why-slow prints a short report with the main reasons and suggestions.

What it detects

| Issue | Severity | What it means | |-------|----------|----------------| | Event loop blocking | High | Sync work or CPU-heavy code is blocking the main thread. | | Synchronous operations | High | readFileSync, writeFileSync, etc. block the event loop. | | Slow async operations | Medium | Some async work takes too long (>500ms). | | Sequential async patterns | Medium | Independent async calls could run in parallel with Promise.all. |

Example output

When issues are found:

============================================================
WHY YOUR BACKEND IS SLOW
============================================================

Main reasons:

🔴 Your backend is slow because the event loop is frequently blocked,
   which causes requests to wait before being processed.
   Mean delay: 45.23ms, Max delay: 120.50ms

🔴 auth.js uses synchronous file operations, which block the event loop.
   Detected: 3 occurrences
   Examples:
     - fs.readFileSync in auth.js (25.30ms)

Suggestions:

• Avoid synchronous operations and heavy CPU work on the main thread.
  Use worker threads for CPU-intensive tasks.
• Replace synchronous operations with their async alternatives
  (fs.promises.readFile, fs.promises.writeFile).

============================================================

When nothing significant is found:

✅ No significant performance issues detected.

How it works

• CLI (bin/why-slow.js) – Runs your app with node --require <hook> and passes a temp results path.
• Hook – Loads in your process, attaches observers, and writes a JSON summary on exit.
• Observers – Event loop delay, sync fs/crypto calls, and (when enabled) async timing.
• Rules engine – Turns observations into issues and suggestions.
• Reporter – Prints the final “why your backend is slow” report.

No server, no config files. Uses only Node.js built-ins.

Requirements

• Node.js ≥ 14.0.0
• No extra dependencies

License

MIT