PerfKit — Local Performance Analyzer

A private, local GTmetrix-style website performance analyzer.
Runs 100% on your machine. Optional AI analysis via Groq (free tier). No data sent anywhere except for AI analysis.

---

Features

Feature	Details
Lighthouse scores	Performance, Accessibility, Best Practices, SEO (0–100, A–F grade)
Core Web Vitals	LCP, FCP, TBT, CLS, TTFB, Speed Index with Good/Needs Improvement/Poor ratings
Waterfall chart	Every network request with DNS/Connect/SSL/Wait/Receive timing breakdown
Filmstrip	Page load progression screenshots at key intervals
Full screenshot	Final rendered page capture
Audit recommendations	Prioritized list with estimated savings (ms / bytes)
History & trends	SQLite-stored runs, line charts per URL over time
AI Analysis	Groq-powered expert summary with prioritized recommendations, quick wins, and Web Vitals explanations

---

Screenshots

Requirements

• Node.js 20 LTS — https://nodejs.org (LTS version)
• Google Chrome — already installed on most Windows machines
• Windows 10/11
• Groq API key (optional) — free at console.groq.com — only needed for AI Analysis tab

---

Quick Start

1. Double-click INSTALL.bat ← installs all npm packages (one-time)
2. Double-click START.bat ← starts both servers + opens browser
3. Open http://localhost:5173

---

Manual Start

Open two terminals:

Terminal 1 — Backend:

cd perfkit/backend
node index.js
# Server running at http://localhost:3001

Terminal 2 — Frontend:

cd perfkit/frontend
npm run dev
# UI running at http://localhost:5173

---

Project Structure

perfkit/
├── backend/
│ ├── index.js Express API server
│ ├── runner.js Lighthouse + Puppeteer analysis engine
│ ├── db.js SQLite database (better-sqlite3)
│ ├── package.json
│ └── perfkit.db ← created automatically on first run
├── frontend/
│ ├── src/
│ │ ├── App.jsx Router + nav
│ │ ├── pages/
│ │ │ ├── Home.jsx URL input + recent runs
│ │ │ ├── Report.jsx Full analysis report (tabs)
│ │ │ └── History.jsx All runs + trend charts
│ │ └── components/
│ │ ├── ScoreGauge.jsx Circular SVG score gauge
│ │ ├── WebVitals.jsx CWV cards with ratings
│ │ ├── WaterfallChart.jsx Network request waterfall
│ │ ├── Filmstrip.jsx Load progression frames
│ │ └── AuditList.jsx Prioritized audit items
│ ├── vite.config.js
│ └── package.json
├── screenshots/ Auto-created, stores .jpg per run
├── INSTALL.bat
├── START.bat
└── README.md

---

API Endpoints

Method	Path	Description
POST	/api/analyze	Submit URL for analysis { url }
GET	/api/runs/:id	Get run result (poll until status=done)
GET	/api/history	All runs, optional ?url=&limit=
GET	/api/urls	Unique URLs with run counts
GET	/api/trend	Trend data ?url=&limit=
DELETE	/api/runs/:id	Delete a run
GET	/api/health	Server health + queue status

---

Analysis Configuration

Edit backend/runner.js to change test settings:

// Change from desktop to mobile:
formFactor: 'mobile',screenEmulation: {mobile: true,width: 375,height: 812, ... }// Change throttling (simulate slower connections):
throttling: {rttMs: 150,// 4G: 150ms RTTthroughputKbps: 1638,// 4G: ~1.6 MbpscpuSlowdownMultiplier: 4,}// Test localhost sites — just enter http://localhost:PORT in the UI// No special config needed

AI Analysis (Optional)

1. Get a free API key at https://console.groq.com
2. Create frontend/.env
3. Add: VITE_GROQ_API_KEY=your_key_here
4. Restart the frontend server

---

Tips

• Testing localhost: Enter http://localhost:3000 (or any port) in the URL bar — works natively
• Staging sites: Any URL accessible from your machine works, including VPN-only URLs
• Re-test: Submit the same URL multiple times to build trend data
• Delete old runs: Click × in History to remove a run from the database
• Database location:backend/perfkit.db — back it up to keep your history

---

Troubleshooting

"Analysis Failed" / Chrome error:

• Make sure Chrome is installed at the default location
• Try: npx puppeteer browsers install chrome in the backend folder

Port already in use:

• Backend uses 3001, frontend uses 5173
• Change in backend/index.js (PORT variable) and frontend/vite.config.js

Very slow analysis:

• Normal — Lighthouse runs a full browser session. Expect 15–45 seconds per URL.
• Complex SPAs or slow servers will take longer.

No filmstrip frames:

• Some pages don't trigger Lighthouse's screenshot audit. This is normal.

---

Tech Stack

• Backend: Node.js, Express, Lighthouse 11, Puppeteer 21, better-sqlite3
• Frontend: React 18, Vite 5, Recharts, React Router
• Database: SQLite (zero-config, single file)
• Fonts: Syne + IBM Plex Mono

All open source. No telemetry. Core analysis is fully local. AI Analysis optionally calls Groq API.