Auditing with Lighthouse

Use Lighthouse and PageSpeed Insights to audit performance and SEO.

Lighthouse is a free auditing tool built into Chrome DevTools. It scores a page on Performance, Accessibility, Best Practices and SEO, with specific recommendations.

Ways to run it

Chrome DevTools - the Lighthouse tab (lab data).
PageSpeed Insights - runs Lighthouse plus real-user field data.
CI tools - Lighthouse CI to catch regressions on every deploy.

Read it wisely

Lighthouse gives lab data on one device and network. Use it to find and fix issues, but trust Search Console field data for the numbers Google actually ranks on.

Example

# Run Lighthouse from the command line
npm install -g lighthouse
lighthouse https://example.com --view

# Or use PageSpeed Insights in the browser:
https://pagespeed.web.dev

When to use it

A developer runs Lighthouse in CI on every pull request to prevent performance regressions from merging before they reach production.
An SEO team uses the Lighthouse SEO audit to quickly surface missing meta descriptions, non-indexable pages, and broken canonicals across a redesign.
A startup uses PageSpeed Insights to get field-data Core Web Vitals for their landing page before and after an optimisation sprint to prove impact.

More examples

Run Lighthouse from CLI

The Lighthouse CLI produces both human-readable HTML reports and machine-readable JSON, enabling score tracking and CI integration.

# Install once
npm install -g lighthouse

# Audit a URL and save full HTML report
lighthouse https://example.com \
  --output html \
  --output-path /tmp/lighthouse-report.html \
  --form-factor mobile \
  --throttling-method simulated

# JSON output for programmatic scoring
lighthouse https://example.com \
  --output json \
  --output-path /tmp/lh.json --quiet
python3 -c "
import json
r = json.load(open('/tmp/lh.json'))
for k in ['performance','seo','accessibility','best-practices']:
    print(k, round(r['categories'][k]['score']*100))
"

Lighthouse in GitHub Actions CI

Running Lighthouse CI on every push catches performance regressions before they reach production and fails the build when scores fall below budget thresholds.

name: Lighthouse CI
on: [push]
jobs:
  lhci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build
      - uses: treosh/lighthouse-ci-action@v11
        with:
          urls: |
            https://staging.example.com/
            https://staging.example.com/shoes/
          budgetPath: ./budget.json
          uploadArtifacts: true

Parse PageSpeed Insights API

The PageSpeed Insights API combines Lighthouse lab scores with real-user CrUX field data in a single response, giving both synthetic and field-data performance signals.

# Fetch Core Web Vitals field data and Lighthouse scores in one call
curl -s \
  "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=https://example.com&strategy=mobile&key=YOUR_KEY" \
  | python3 -c "
import sys, json
r = json.load(sys.stdin)
cat = r['lighthouseResult']['categories']
for k, v in cat.items():
    print(f"{k:20} {int(v['score']*100)}/100")
"

Discussion

Be the first to comment on this lesson.