lighthouse-perf

Overview

The Core Web Vitals are Google's three canonical user-experience metrics (web-vitals (opens in new window)):

INP became a stable Core Web Vital in 2024, replacing FID (web-vitals (opens in new window)). The canonical measurement standard is the 75th percentile of page loads, segmented across mobile and desktop (web-vitals (opens in new window)).

This skill covers Lighthouse CI (@lhci/cli) - the official Google Chrome team tool for running Lighthouse on every PR and asserting against budgets (lhci (opens in new window)).

When to use

• The project ships a web frontend (Next.js, Vite, Remix, plain static, etc.).
• The team has documented Web Vitals NFRs (per non-functional-requirement-extractor) and needs CI enforcement.
• A PR's perf delta vs. main needs to be visible (regression-block or just-warn).
• The team uses Lighthouse for accessibility / SEO / best-practices audits beyond perf.

If the project is a backend API or a CLI tool, this skill doesn't apply - use k6-load-testing or a sibling load runner for backend perf.

Install

npm install --save-dev @lhci/cli

(Per lhci (opens in new window); the docs reference @lhci/cli@0.15.x as the current major.) Pin to a specific minor in CI for determinism.

Configure

Create .lighthouserc.js (or .lighthouserc.json) at the project root. The canonical shape per lhci (opens in new window):

module.exports = {
  ci: {
    collect: {
      // What to audit
      url: [
        'http://localhost:3000/',
        'http://localhost:3000/dashboard',
        'http://localhost:3000/pricing',
      ],
      // How many runs per URL - median report wins; 3 is canonical for stability
      numberOfRuns: 3,
      // Lighthouse settings
      settings: {
        preset: 'desktop',                       // or 'mobile' (default)
        chromeFlags: '--no-sandbox',              // CI-runner-friendly
      },
      // Use a static-server when running headless in CI
      startServerCommand: 'npm run start',
      startServerReadyPattern: 'ready on',
    },
    assert: {
      // Canonical Web Vitals budgets per web.dev/articles/vitals
      assertions: {
        'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],   // 2.5s
        'interaction-to-next-paint': ['error', { maxNumericValue: 200 }],   // 200ms
        'cumulative-layout-shift':   ['error', { maxNumericValue: 0.1 }],    // 0.1
        // Lighthouse category scores (0-1)
        'categories:performance':    ['warn',  { minScore: 0.9 }],
        'categories:accessibility':  ['error', { minScore: 0.95 }],
        'categories:best-practices': ['warn',  { minScore: 0.9 }],
      },
    },
    upload: {
      // Where to upload the .json reports for trend analysis
      target: 'temporary-public-storage',   // or 'lhci' for self-hosted server
    },
  },
};

Assertion levels per lhci (opens in new window):

• 'error' - fails the CI run (exits non-zero).
• 'warn' - surfaces in the report but doesn't fail.
• 'off' - disabled (useful for opt-out per-page).

Running

The canonical invocation per lhci (opens in new window):

lhci autorun

autorun runs three phases in sequence:

1. collect - start the server (if startServerCommand set), run Lighthouse N times per URL.
2. assert - compare results against the assertion config; exit non-zero on error-level failures.
3. upload - upload reports to the configured target for trend tracking.

For finer control, the phases can run independently: lhci collect, lhci assert, lhci upload.

Running specific URLs

For a single PR-relevant audit:

lhci collect --url=http://localhost:3000/dashboard --numberOfRuns=3
lhci assert

CI integration

# .github/workflows/lighthouse.yml
name: lighthouse

on:
  pull_request:
    paths:
      - 'src/**'
      - 'package.json'
      - 'package-lock.json'

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci

      - name: Build
        run: npm run build

      - name: Lighthouse CI
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}   # optional, for PR comments
        run: npx lhci autorun

      - name: Upload Lighthouse reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: lighthouse-reports
          path: .lighthouseci/
          retention-days: 14

The optional LHCI_GITHUB_APP_TOKEN (set up via the Lighthouse CI GitHub App) enables PR comments showing the per-metric delta vs. the main branch's last green run.

Authoring budgets

Budget authoring is part of Lighthouse CI configuration: picking per-route LCP / INP / CLS thresholds by traffic class, resource-size caps in budget.json, the assertMatrix config shape, and how to validate a new budget against production before committing it, are all in references/budgets.md. Start there when the project has no budgets yet or the existing ones need a redesign.

Mobile vs desktop budgets

LCP / INP thresholds are the same across mobile and desktop, but mobile is consistently slower in practice - the same JS bundle runs on a less-powerful CPU over a less-stable network.

Common pattern: separate .lighthouserc.mobile.js and .lighthouserc.desktop.js, run both in CI. The mobile run uses preset: 'mobile' (default) which applies CPU + network throttling to simulate a mid-range Android device.

# Run both
LHCI_BUILD_CONTEXT__GITHUB_BASE_URL=https://github.com/... \
  npx lhci autorun --config=.lighthouserc.mobile.js
npx lhci autorun --config=.lighthouserc.desktop.js

Anti-patterns

Lab vs field

Lighthouse CI measures lab data (synthetic; deterministic runner). Field data (real-user metrics, RUM) is measured by Web Vitals JS in production. Both matter:

Lighthouse CI catches per-PR regressions; field data tracks the 75th-percentile threshold per web-vitals (opens in new window). Don't substitute one for the other.

References

• web-vitals (opens in new window) - canonical Core Web Vitals definitions and thresholds (LCP ≤2.5s, INP ≤200ms, CLS ≤0.1; 75th-percentile measurement; INP-replaces-FID in 2024).
• lhci (opens in new window) - Lighthouse CI canonical install, lhci autorun, configuration shape, assertion levels.
• references/budgets.md - drafting per-route budgets and budget.json resource-size caps at design time.
• perf-budget-gate - downstream unified gate aggregating Lighthouse + load-runner verdicts.
• non-functional-requirement-extractor - upstream skill that surfaces Web Vitals NFRs from PRDs.