frontend-performance-audit

Files (1)

• SKILL.md

SKILL.md (first lines)

# Frontend Performance Audit

> **Measure, don't estimate.** "The page feels fast" is not evidence. "LCP 3.1s at 4x CPU throttle, 2.2s of it server response time" is evidence.

This skill wires `chrome-devtools-mcp` as the **measurement instrument** in a browser toolkit that already has drivers. It exists because functional browser automation and performance measurement are different jobs, and the tools that do the first one well do not do the second one at all.

## The problem this solves

Most agent harnesses accumulate two or three browser tools that all click, screenshot, and read the DOM. None of them measure. So performance work falls back to one of two bad options:

1. **Field data** (Chrome UX Report, a partner/vendor analytics dashboard, RUM). Accurate but lagging — typically a 28-day rolling 75th percentile. You cannot use it to test a fix you made this morning.
2. **A public URL scanner** (PageSpeed Insights, Lighthouse CI against a deployed URL). Fast, but it can only reach pages that are publicly reachable and unauthenticated.

Neither option can measure **an authenticated page, an embedded iframe app, or a password-protected staging store**. That is precisely where most real product surfaces live.

`chrome-devtools-mcp` closes that gap because it can attach to a browser you have already logged into, and trace the page in situ.

## When to use

- Measuring LCP, CLS, INP, or TBT on any route, especially a lab measurement of a fix before it ships
- Any certification with hard performance thresholds (Built for Shopify, a marketplace listing bar, an SLA)
- Diagnosing *why* a route is slow — the trace insights attribute the time, rather than just scoring it
- Reproducing a slow experience on constrained hardware or a poor network (CPU and network throttling)
- Lighthouse accessibility, SEO, best-practices, or agentic-browsing scores
- Suspected memory leak or unbounded heap growth in a long-lived tab
- Auditing a page that requires an authenticated session and therefore cannot be scanned from outside

## When NOT to use

This is the part that keeps the toolkit coherent. **Do not use this skill as a general browser driver.**

- ❌ Functional user journeys, click-and-assert flows, form submission → use your committed E2E suite
- ❌ Regression tests that must run in CI → write a spec, not an agent session
- ❌ Scraping, bulk HTTP fetching, exploratory navigation → use your scripted CDP harness
- ❌ "Take a screenshot of this page" → whatever driver you already have open; do not start a second browser
- ❌ Anything an existing passing test already covers

Adding a third browser tool is only justified if it is confined to the job the others cannot do. Measurement is that job. If you find yourself clicking through a checkout with this tool, you have broken the routing rule.

## The routing rule

One table. Read the job, pick the tool, do not improvise.

| Job | Tool | Why |
|---|---|---|
| Core Web Vitals (LCP / CLS / INP / TBT) | **chrome-devtools-mcp** | Only tool that records and parses a trace |
| Page-load trace and time attribution | **chrome-devtools-mcp** | `performance_analyze_insight` explains the number |
| CPU / network throttling, device emulation | **chrome-devtools-mcp** | `emulate` exposes both |
| Lighthouse a11y / SEO / best practices | **chrome-devtools-mcp** | `lighthouse_audit` |
| Heap snapshot, leak hunting, retainer paths | **chrome-devtools-mcp** | 12 heap tools; nothing else has them |
| Committed regression test, CI gate | **E2E framework (Playwright/Cypress specs)** | Must run headless, unattended, on every push |
| Interactive journey validation in a logged-in session | **Existing MCP browser driver** | Already wired, already authenticated |
| Scripted exploration, scraping, bulk HTTP | **Scripted CDP harness** | Cheapest per action, no MCP round-trip |
| Coordinate clicks through iframes / shadow DOM | **Scripted CDP harness** | Compositor-level hit testing |

**The one-line version:** if the deliverable is a *number*, use chrome-devtools-mcp. If the deliverable is a *pass/fail on behaviour*, use the driver or the test suite.

## Configuration

Pin the version. Do not use `@latest` in a checked-in config — this package ships roughly monthly and an unpinned upgrade will change tool behaviour underneath a working audit.

### Launch its own browser (default; use for public URLs)

```json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@1.6.0",
        "--isolated",
        "--no-usage-statistics"
      ]
    }
  }
}
```

`--isolated` uses a throwaway user-data-dir that is cleaned up afterwards, so an audit never mutates your real profile.

### Attach to a browser you are already logged into (use for authenticated / embedded pages)

This is the mode that earns the tool its place. Start Chrome with remote debugging on a dedicated profile:

```bash
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.chrome-debug-profile"
```

Log in once in that window, then point the server at it:

```json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@1.6.0",
        "--browserUrl",
        "http://127.0.0.1:9222",
        "--no-usage-statistics"
      ]
    }
  }
}
```

If your project already launches a CDP Chrome on 9222 for E2E testing, reuse it. The session, cookies, and login you already have are the whole point — you get to trace the real authenticated page rather than a logged-out shell.

### Flags worth knowing

| Flag | Use |
|---|---|
| `--browserUrl <url>` | Attach to a running debuggable Chrome |
| `--isolated` | Temporary profile, auto-cleaned |
| `--headless` | No UI; note that headless can shift timings, so baseline in one mode and stay there |

From jpantsjoha/ai-native-developer-experience, Apache-2.0.

More from jpantsjoha/ai-native-developer-experience