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

lighthouse-runner