Lighthouse CI Setup Guide

Automate Lighthouse performance audits on every pull request using GitHub Actions. Enforce performance budgets, track score trends, and block deploys when scores regress.

Installation

# Install globally (local use)
npm install -g @lhci/cli

# Or add to your project
npm install --save-dev @lhci/cli

lighthouserc.js Configuration

// lighthouserc.js
module.exports = {
  ci: {
    collect: {
      // Build and serve your app, then audit these URLs
      startServerCommand: 'npm run start',
      startServerReadyPattern: 'ready on',
      url: [
        'http://localhost:3000/',
        'http://localhost:3000/pricing',
        'http://localhost:3000/dashboard',
      ],
      numberOfRuns: 3,   // median of 3 runs reduces score variance
      settings: {
        // Simulated throttling (default) — consistent across machines
        throttlingMethod: 'simulate',
        // Remove these for mobile simulation:
        // formFactor: 'mobile', screenEmulation: { mobile: true }
      },
    },
    assert: {
      preset: 'lighthouse:recommended',
      assertions: {
        // Fail CI if scores fall below these minimums
        'categories:performance':    ['error', { minScore: 0.9 }],
        'categories:accessibility':  ['error', { minScore: 0.9 }],
        'categories:best-practices': ['error', { minScore: 0.9 }],
        'categories:seo':            ['error', { minScore: 0.9 }],

        // Specific Web Vitals thresholds (more stable than aggregate score)
        'largest-contentful-paint':  ['error', { maxNumericValue: 2500 }],
        'total-blocking-time':       ['error', { maxNumericValue: 200 }],
        'cumulative-layout-shift':   ['error', { maxNumericValue: 0.1 }],
        'first-contentful-paint':    ['warn',  { maxNumericValue: 1800 }],

        // Resource budgets
        'uses-optimized-images':     'warn',
        'unused-javascript':         'warn',
        'render-blocking-resources': 'warn',
      },
    },
    upload: {
      target: 'temporary-public-storage',  // free 30-day storage
      // For GitHub PR comments, add LHCI_GITHUB_APP_TOKEN secret
      githubToken: process.env.LHCI_GITHUB_APP_TOKEN,
    },
  },
};

GitHub Actions Workflow

# .github/workflows/lighthouse-ci.yml
name: Lighthouse CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }

      - name: Install dependencies
        run: npm ci

      - name: Build application
        run: npm run build

      - name: Run Lighthouse CI
        run: npx lhci autorun
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}

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

Lighthouse Score Targets

Self-Hosted LHCI Server

# Run LHCI server locally (stores results in SQLite)
npx @lhci/cli server --storage.storageMethod=sql \
  --storage.sqlDialect=sqlite \
  --storage.sqlDatabasePath=./lhci.db

# Or with Docker
docker run --rm -p 9001:9001 patrickhulce/lhci-server

# Update lighthouserc.js upload section to point to your server:
upload: {
  target: 'lhci',
  serverBaseUrl: 'http://lhci.internal:9001',
  token: process.env.LHCI_BUILD_TOKEN,
}

Common Issues & Fixes

• Score varies run-to-run — Use numberOfRuns: 3, assert on specific metrics not aggregate score
• Server not ready before collect — Tune startServerReadyPattern to match your server's ready log message
• Chrome not found in CI — Add apt-get install -y google-chrome-stable or use --chrome-flags="--no-sandbox"
• Auth-protected pages show 0 scores — Add puppeteerScript to lighthouserc.js to log in before auditing
• Performance budget too strict — Use warn instead of error for non-critical assertions during initial setup