find-bottleneck-perf 🔍

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

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

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

# 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

# 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:

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

find-bottleneck https://example.com --export report.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