$devvkit learn --librarie lighthouse-guide

Lighthouse Guide

[performance][audit][seo][accessibility]

Performance & Profiling

Install

# CLI (via Node)
npm install -g lighthouse
# or use directly in Chrome DevTools Audits tab
# API: github.com/GoogleChrome/lighthouse

Lighthouse runs a battery of audits against any web page and produces a score (0-100) across five categories: Performance, Accessibility, Best Practices, SEO, and Progressive Web App readiness. Each audit comes with actionable recommendations.

The CLI is your CI best friend — run lighthouse as part of your build pipeline, output a JSON report, and fail the build if scores drop below a threshold. Use `--preset=desktop` to simulate desktop or `--chrome-flags="--headless"` for server environments.

For deeper analysis, use the Node API to run programmatic audits. Pair with Puppeteer to audit authenticated pages or single-page app routes. GUI: Chrome DevTools Audits tab, or Lighthouse Report Viewer for visual diffing.

Basic Usage

Run audit— Audit a URL and save HTML report.

lighthouse https://example.com --view      # Opens report in browser
lighthouse https://example.com --output html --output-path ./report.html
lighthouse https://example.com --output json --output-path ./report.json

Simulate mobile— Emulate mobile device.

lighthouse https://example.com --preset=desktop    # Desktop throttling
lighthouse https://example.com --preset=perf        # Performance-only audits
lighthouse https://example.com --form-factor=tablet

Only performance— Run specific categories.

lighthouse https://example.com --only-categories=performance,accessibility
lighthouse https://example.com --skip-audits=uses-http2,unused-css-rules

CI Integration

Fail CI on regression— Exit non-zero below score.

lighthouse https://example.com --output json | jq -r '.categories.performance.score * 100'
# Fail if score < 90
lhci autorun  # Lighthouse CI

Lighthouse CI— Track scores over time.

# .lighthouserc.json
{
  "ci": {
    "collect": { "url": ["https://example.com"], "numberOfRuns": 3 },
    "assert": {
      "assertions": {
        "categories:performance": ["warn", { "minScore": 0.9 }],
        "categories:accessibility": ["error", { "minScore": 0.95 }]
      }
    }
  }
}

# Run:
npx lhci autorun

Budget Monitoring

Performance budget— Set resource budgets.

# budget.json
[
  {
    "path": "/",
    "timings": [{ "metric": "interactive", "budget": 3000 }],
    "resourceSizes": [
      { "resourceType": "script", "budget": 200 },
      { "resourceType": "total", "budget": 500 }
    ]
  }
]

lighthouse https://example.com --budget-path=budget.json

Node API

Node API — custom— Programmatic audit.

import lighthouse from 'lighthouse'
import * as chromeLauncher from 'chrome-launcher'

const chrome = await chromeLauncher.launch({ chromeFlags: ['--headless'] })
const options = { logLevel: 'info', output: 'json', port: chrome.port }
const runnerResult = await lighthouse('https://example.com', options)
const score = runnerResult.lhr.categories.performance.score * 100
console.log(`Performance: ${score}`)
await chrome.kill()

Advanced Tricks

Audit with auth— Authenticated pages via Puppeteer.

import puppeteer from 'puppeteer'
import lighthouse from 'lighthouse'

const browser = await puppeteer.launch({ headless: 'new' })
const page = await browser.newPage()
await page.goto('https://example.com/login')
await page.type('#email', 'user@example.com')
await page.type('#password', 'secret')
await page.click('#login-btn')
await page.waitForNavigation()

// Now run Lighthouse on the authenticated session
const { lhr } = await lighthouse(page.url(), {
  port: new URL(browser.wsEndpoint()).port,
  output: 'json',
})
await browser.close()

Diff reports— Compare two runs.

lighthouse https://example.com --output json -o before.json
# make changes...
lighthouse https://example.com --output json -o after.json

# Use lighthouse-report diff or:
jq '{before: .categories.performance.score, after: .categories.performance.score}' before.json after.json