lighthouse-audit

name	lighthouse-audit
description	Automated Lighthouse audit for Next.js apps. Builds the production app, runs @lhci/cli across key URLs, scores all five categories, and produces a prioritized fix plan mapped to concrete Next.js code changes.
allowed-tools	Read, Write, Edit, Glob, Grep, Bash
argument-hint	[url1,url2,...] [--no-build] [--categories performance,accessibility,seo,best-practices,pwa]

Lighthouse Audit Skill

Automated Lighthouse audit with full report and prioritized Next.js fix plan.

Reference Files:

• report-analysis.md — JSON structure, score thresholds, metric descriptions
• fix-mapping.md — Audit ID → Next.js fix mapping

Overview

This skill runs in the target Next.js project (not in the plugin repo). It:

1. Builds the production app
2. Runs Lighthouse via @lhci/cli with a generated config
3. Parses JSON reports from .lighthouseci/
4. Produces a scored summary and a prioritized action plan

Step-by-Step Protocol

Step 1 — Detect project configuration

Read package.json and extract:

• scripts.build — command to build (typically next build)
• scripts.start — command to start production server (typically next start)
• Default port — scan scripts for -p <port> flag, default to 3000

If package.json is missing or has no build/start scripts, stop and ask the user.

Step 2 — Determine target URLs

If URL argument provided: use it directly.

If no argument:

• Default to http://localhost:<port>/ (homepage)
• Also check if common routes exist by scanning app/ directory for top-level directories (e.g. app/dashboard/ → add /dashboard)
• Limit to max 5 URLs to keep audit time reasonable

Production URL (no localhost):

• Skip Steps 3–4 (no build or server needed)
• Jump directly to Step 5

Step 3 — Build production app (localhost only)

npm run build

This step is mandatory for valid performance scores. A dev build produces unminified bundles with source maps and dev overlays — results would be meaningless. If build fails, report the error and stop.

Skip this step if --no-build flag was passed (assumes server is already running).

Step 4 — Write lighthouserc.json

Write a config file to the project root. Use startServerCommand: "npm start" so lhci handles server lifecycle. Do not include assert — the skill performs its own analysis rather than relying on lhci's pass/fail gate.

{
  "ci": {
    "collect": {
      "url": ["<url1>", "<url2>"],
      "startServerCommand": "npm start",
      "startServerReadyPattern": "Ready|started server on|listening on",
      "startServerReadyTimeout": 30000,
      "numberOfRuns": 3,
      "settings": {
        "chromeFlags": "--no-sandbox --headless=new",
        "onlyCategories": ["performance", "accessibility", "best-practices", "seo", "pwa"]
      }
    },
    "upload": {
      "target": "filesystem",
      "outputDir": ".lighthouseci"
    }
  }
}

Adjust url array and onlyCategories based on user's argument. If --no-build was passed, remove startServerCommand (server already running).

Step 5 — Run the audit

npx --yes @lhci/cli@latest autorun --config=lighthouserc.json

Always append || true or use ; echo "exit:$?" to capture the exit code without aborting the pipeline — lhci exits non-zero when scores fall below any threshold, which is exactly the case we want to analyze.

npx --yes @lhci/cli@latest autorun --config=lighthouserc.json; LHCI_EXIT=$?
echo "lhci exit code: $LHCI_EXIT"

After the run, verify .lighthouseci/ directory was created:

ls .lighthouseci/

Step 6 — Parse reports

Reports land in .lighthouseci/lhr-<timestamp>-<hash>.json — one file per URL per run. When numberOfRuns: 3, lhci also writes a manifest.json that identifies the median run per URL.

Read manifest.json:

cat .lighthouseci/manifest.json

For each URL, find the representative: true entry — that's the median run. Read its corresponding lhr-*.json file for analysis.

See report-analysis.md for the full JSON structure and how to extract scores and failing audits.

Step 7 — Generate the report

Produce a Markdown report structured as follows:

## Lighthouse Audit Report — <date>

### Scores Summary

| URL | Performance | Accessibility | Best Practices | SEO | PWA |
|-----|-------------|---------------|----------------|-----|-----|
| /   | 🟢 94       | 🟡 78         | 🟢 92          | 🟢 98 | ⚫ N/A |

Legend: 🟢 ≥ 90 · 🟡 50–89 · 🔴 < 50 · ⚫ not audited

### Core Web Vitals

| Metric | Value | Target | Status |
|--------|-------|--------|--------|
| LCP    | 3.2 s | < 2.5 s | 🔴 |
| FCP    | 1.4 s | < 1.8 s | 🟢 |
| CLS    | 0.14  | < 0.1  | 🟡 |
| INP    | 180 ms | < 200 ms | 🟢 |
| TTFB   | 420 ms | < 800 ms | 🟢 |

### Failing Audits

Group by category. For each failing audit include:
- Audit title
- Current value / score
- Brief description of impact
- Specific elements or resources flagged by Lighthouse (from `details` field)

Step 8 — Generate action plan

For every failing audit (score < 0.9), map it to a concrete Next.js fix using fix-mapping.md.

Structure the plan as a prioritized checklist:

## Action Plan

Sorted by estimated impact (high → low). Check each item after fixing and re-run
the audit to verify improvement.

### 🔴 High Impact

- [ ] **LCP too slow (3.2 s)** — Add `priority` prop to the hero `<Image>` in
  `app/(home)/page.tsx`. LCP element: `<img src="/hero.jpg">` flagged at line …
  Reference: `performance-optimization` skill → Core Web Vitals section.

### 🟡 Medium Impact

- [ ] **CLS: layout shift from web font** — Add `display: 'swap'` to `next/font`
  config and ensure font subsets are loaded. See `layout.tsx`.

### ℹ️ Low Impact / Best Practices

- [ ] **Missing `<meta name="description">`** — Add `metadata.description` export
  to each page's `page.tsx`. See Next.js Metadata docs.

Finish by suggesting: Re-run /lighthouse-audit after addressing high-impact items.

Step 9 — Cleanup

Remove the generated lighthouserc.json from the project root (it's ephemeral):

rm lighthouserc.json

Leave .lighthouseci/ in place — the user may want to browse the HTML reports there. Remind them to add .lighthouseci to .gitignore.

Argument Reference

Argument	Default	Description
url1,url2,...	auto-detected from app/	Comma-separated URLs to audit
--no-build	off	Skip npm run build (server already running)
--categories	all five	Comma-separated: performance,accessibility,best-practices,seo,pwa

Related Skills

• performance-optimization — Bundle analysis, React rendering, database queries, and Next.js-specific fixes referenced in the action plan
• accessibility-audit — Deep manual accessibility review beyond Lighthouse's automated checks
• playwright-cli — Browser automation for auditing pages behind authentication