find-bottleneck-perf 🔍

One command. One answer. Who's slowing down your website—Frontend, Backend, or Infrastructure?

``bash
npx find-bottleneck-perf https://your-website.com
`

!Node.js
!License
!npm

---

Why?

You've got a slow website. Lighthouse gives you 47 metrics. DevTools shows 200 network requests. Your PM asks: "Is it the frontend team or the backend team?"

find-bottleneck-perf answers that question in seconds.

---

Install

`bash


Run directly (no install)

npx find-bottleneck-perf https://example.com

Or install globally

npm install -g find-bottleneck-perf
find-bottleneck https://example.com
`

---

Usage

`bash


Basic analysis

find-bottleneck https://example.com

Simulate slow network (Slow 3G, Fast 3G, 4G, WiFi)

find-bottleneck https://example.com --network slow-3g

Export full report to JSON

find-bottleneck https://example.com --export report.json

Combine options

find-bottleneck https://example.com --network fast-3g --export report.json
`

---

What You Get

`
════════════════════════════════════════════════════════════
FIND-BOTTLENECK │ Performance Analysis Report
════════════════════════════════════════════════════════════

┌─ THE VERDICT
│
│ 🖥️ Primary Bottleneck: FRONTEND
│
│ Scores: Frontend=19 Backend=5 Infra=2
└───────────────────────────────────────────────────────────

┌─ EVIDENCE
│
│ [Frontend]
│ ▸ Massive JS bundle (5.66 MB). Implement code splitting.
│ ▸ 35 render-blocking resources. Use async/defer.
└───────────────────────────────────────────────────────────

┌─ RECOMMENDATIONS
│
│ 👉 Implement code splitting (dynamic imports) and tree shaking.
│ 👉 Profile JavaScript with Chrome DevTools Performance tab.
└───────────────────────────────────────────────────────────
`

---

Verdicts Explained

| Verdict | What It Means | Typical Causes |
|---------|---------------|----------------|
| Frontend | Browser is struggling | Large JS bundles, render-blocking resources, heavy images |
| Backend | Server is slow | Slow APIs, database queries, missing caching |
| Infra | Network is the problem | High latency, slow DNS, distant servers |
| Mixed | Multiple issues | Problems in more than one area |
| Optimized | You're good! | No significant issues detected |

---

Metrics Collected

| Category | Metrics |
|----------|---------|
| Navigation | DNS, TCP, TLS, TTFB, Server Processing |
| Web Vitals | FCP, LCP, Total Blocking Time |
| Resources | JS/CSS/Image sizes, Render-blocking count |
| APIs | Request count, Avg/Max latency, Failed requests |

---

Network Throttling

Test how your site performs on real-world connections:

`bash
find-bottleneck https://example.com --network slow-3g
`

| Preset | Speed | Latency | Use Case |
|--------|-------|---------|----------|
| slow-3g | 500 Kbps | 400ms | Worst-case mobile |
| fast-3g | 1.6 Mbps | 150ms | Typical mobile |
| 4g | 4 Mbps | 20ms | Good mobile |
| wifi | 30 Mbps | 2ms | Office/Home WiFi |

---

JSON Export

`bash
find-bottleneck https://example.com --export report.json
`

`json
{
"url": "https://example.com",
"verdict": {
"primary": "Frontend",
"scores": { "Frontend": 15, "Backend": 5, "Infra": 2 }
},
"metrics": { ... },
"evidence": [
{ "category": "Frontend", "message": "Massive JS bundle (5.15 MB)..." }
],
"recommendations": [
"Implement code splitting...",
"Profile database queries..."
]
}
``

---

How It Works

1. Launches headless Chrome via Puppeteer
2. Intercepts all network requests (APIs, JS, CSS, images)
3. Extracts Navigation Timing API and PerformanceObserver data
4. Applies weighted heuristics to score Frontend/Backend/Infra
5. Generates evidence-based recommendations

---

Requirements

- Node.js 18+
- ~400MB disk space (for Chromium, installed automatically)

---

License

ISC © Karthik Sake