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.