Lighthouse Runner

Runs Google Lighthouse audits via Playwright for comprehensive web quality assessment including SEO, Performance, Accessibility, and Best Practices.

Features

URL Analysis: Direct analysis of live URLs
Local File Support: Automatically starts a local server for HTML files
Multiple Categories: SEO, Performance, Accessibility, Best Practices
JSON Output: Machine-readable results for integration
Core Web Vitals: LCP, FID, CLS metrics
Cross-Platform: Works on Windows, macOS, and Linux (no Bash required)

Usage

Installation

cd ${CLAUDE_PLUGIN_ROOT}/skills/lighthouse-runner
npm install
npm run build

Run Analysis

# Analyze a URL
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/lighthouse-runner/src/index.ts https://example.com

# Analyze a local HTML file (auto-starts local server)
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/lighthouse-runner/src/index.ts path/to/file.html

# Analyze a development server
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/lighthouse-runner/src/index.ts http://localhost:3000

# Output JSON format
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/lighthouse-runner/src/index.ts https://example.com --json

# Specify categories
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/lighthouse-runner/src/index.ts https://example.com --categories=seo,accessibility

Using Built Version

# After npm run build
node ${CLAUDE_PLUGIN_ROOT}/skills/lighthouse-runner/dist/index.js https://example.com

Output Scores

| Category | Description | Key Metrics | |----------|-------------|-------------| | Performance | Page load speed | LCP, FID, CLS, TTFB, Speed Index | | SEO | Search engine optimization | Meta tags, crawlability, mobile | | Accessibility | WCAG compliance | Color contrast, ARIA, keyboard | | Best Practices | Web standards | HTTPS, console errors, image aspect |

Score Interpretation

| Score | Rating | Action | |-------|--------|--------| | 90-100 | Good (Green) | Maintain | | 50-89 | Needs Improvement (Orange) | Optimize | | 0-49 | Poor (Red) | Priority fix |

Output Format

Text Report

# Lighthouse Report: https://example.com

## Scores
- Performance:   85/100 [########--]
- SEO:           95/100 [#########-]
- Accessibility: 78/100 [#######---]
- Best Practices: 92/100 [#########-]

## Core Web Vitals
- LCP: 2.1s [GOOD]
- FID: 45ms [GOOD]
- CLS: 0.050 [GOOD]

## Additional Metrics
- TTFB: 320ms
- Speed Index: 3.2s
- FCP: 1.8s
- TBT: 120ms

## Performance Issues

1. **Eliminate render-blocking resources** (45%)
   3 resources blocking first paint
2. **Serve images in next-gen formats** (60%)
   Use WebP or AVIF

JSON Output

{
  "url": "https://example.com",
  "timestamp": "2024-01-15T10:00:00Z",
  "lighthouseVersion": "12.0.0",
  "scores": {
    "performance": 85,
    "seo": 95,
    "accessibility": 78,
    "best-practices": 92
  },
  "metrics": {
    "lcp": 2100,
    "fid": 45,
    "cls": 0.05,
    "ttfb": 320,
    "speedIndex": 3200,
    "fcp": 1800,
    "tbt": 120
  },
  "audits": {
    "performance": [...],
    "seo": [...],
    "accessibility": [...],
    "best-practices": [...]
  }
}

Local File Analysis

When analyzing local HTML files, the runner:

Starts a temporary HTTP server using serve
Runs Lighthouse against the local URL
Shuts down the server after analysis
Returns results

Note: Local file analysis may not accurately reflect production performance due to:

No network latency
No server response time
Missing CDN optimization

Next.js/Remix Support

For JavaScript frameworks, analyze the running development or production server:

# Start your dev server first
npm run dev  # Starts at http://localhost:3000

# Then run Lighthouse against it
npx tsx src/index.ts http://localhost:3000

# For production build analysis
npm run build && npm run start
npx tsx src/index.ts http://localhost:3000

Integration with Other Skills

Combined SEO Audit

For comprehensive SEO analysis:

Static Analysis (seo-analyzer): Quick meta tag and structure check
Runtime Analysis (lighthouse-runner): Performance and rendered page check
Lookup Reference (seo-lookup): Guidance for fixing issues

# Run static analysis first (fast)
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/seo-analyzer/src/index.ts file.html

# Then run Lighthouse (slower but comprehensive)
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/lighthouse-runner/src/index.ts http://localhost:3000

Requirements

Node.js 18+
Chromium browser (installed automatically via postinstall)
Sufficient memory for headless Chrome (~500MB)

Troubleshooting

Browser Not Found

If Playwright can't find Chromium:

cd ${CLAUDE_PLUGIN_ROOT}/skills/lighthouse-runner
npx playwright install chromium

Timeout Issues

For slow pages, increase the timeout:

npx tsx src/index.ts https://slow-site.com --timeout=120

WSL/Linux Issues

On WSL or headless Linux, you may need additional dependencies:

# Install required libraries for Playwright
npx playwright install-deps chromium