/perf-audit

name: perf-audit
description: Run Lighthouse performance audit with auto-fix for common issues. Use when user wants to check or improve site performance.
argument-hint: "<url>"
allowed-tools: Bash, Read, Edit, Grep, Glob

Performance Audit

Run Lighthouse against the project and fix performance issues.

Process

Step 1: Find the URL

• Check if dev server is running (try common ports: 3000, 5173, 4321, 8080)
• Check package.json scripts for dev/start commands
• Ask user for URL if not auto-detected
• If no server running, suggest starting one first

Step 2: Run Lighthouse

node ${CLAUDE_PLUGIN_ROOT}/tools/lighthouse-runner.mjs <url>

Parse JSON output for scores and opportunities.

Step 3: Report Scores & Core Web Vitals

Present all four Lighthouse scores:

• Performance (target 90+)
• Accessibility (target 90+)
• Best Practices (target 90+)
• SEO (target 100)

Report Core Web Vitals with targets:

• **LCP** (Largest Contentful Paint): target <2.5s — report the LCP element from `lcp_element`
• **TBT** (Total Blocking Time): target <200ms — proxy for INP
• **CLS** (Cumulative Layout Shift): target <0.1
• **FCP** (First Contentful Paint): target <1.8s
• **SI** (Speed Index): target <3.4s

Step 4: Identify Root Causes

Before fixing, identify what's actually causing problems:

**LCP too high?** Check `lcp_element` in results — fix THAT specific element:

• If it's an `<img>`: preload it, use WebP, add fetchpriority="high"
• If it's text: check web font loading, add font-display: swap
• If it's a background image: preload via `<link rel="preload">`

**CLS too high?** Check diagnostics for layout shift sources:

• Images without width/height → add dimensions (scanner already checks this)
• Dynamic content injected above fold → reserve space with CSS
• Web fonts causing FOUT → add font-display: optional or swap

**Unused resources?** Check `wasted_resources`:

• `unused_js_kb` > 100KB → code splitting or tree shaking needed
• `unused_css_kb` > 50KB → purge unused CSS (PurgeCSS, Tailwind purge)

**Third-party scripts slow?** Check `third_party_impact`:

• Analytics blocking >100ms → defer/async load
• Ad scripts blocking >200ms → lazy load below fold
• Chat widgets → load on user interaction, not page load

Step 5: Apply Fixes

For each opportunity, apply fixes using Edit tool:

**Performance fixes (high impact first):**

• **Render-blocking resources** → add `defer` or `async` to non-critical scripts
• **Unused JavaScript** → recommend code splitting, dynamic imports, tree shaking
• **Unused CSS** → recommend PurgeCSS or Tailwind purge config
• **LCP image not preloaded** → add `<link rel="preload" as="image" href="...">`
• **Images not lazy-loaded** → add `loading="lazy"` to below-fold images
• **Images without dimensions** → add `width` and `height` attributes
• **No preconnect** → add `<link rel="preconnect" href="...">` for external origins
• **Font display** → add `font-display: swap` to @font-face declarations
• **Third-party scripts** → defer non-essential scripts, lazy load on interaction

**Accessibility fixes:**

• Missing alt text (also caught by SEO scanner)
• Missing form labels → add `<label>` elements
• Low contrast → adjust colors
• Missing landmark regions → add `<main>`, `<nav>`, `<footer>`

Step 6: Graceful Degradation

• **No Chrome**: report "Chrome needed for Lighthouse. Install Chrome or Chromium."
• **Lighthouse timeout**: return partial results with warning
• **No dev server**: suggest starting one, or test against production URL

Key Principle

**Fix, don't just audit.** Identify the specific elements causing problems. Apply every automated fix possible. For build-tool changes (code splitting, tree shaking), provide exact config recommendations.