lighthouse-ci

Overview

Lighthouse CI runs Google Lighthouse audits automatically on every PR. Set performance budgets, track Core Web Vitals over time, and prevent regressions. Catches performance issues before they reach production.

Instructions

Step 1: Configuration

// lighthouserc.js — Lighthouse CI config
module.exports = {
  ci: {
    collect: {
      url: [
        'http://localhost:3000/',
        'http://localhost:3000/dashboard',
        'http://localhost:3000/pricing',
      ],
      startServerCommand: 'npm run start',
      startServerReadyPattern: 'ready on',
      numberOfRuns: 3,                      // average 3 runs for stability
      settings: {
        preset: 'desktop',                  // or 'mobile' (default)
      },
    },
    assert: {
      assertions: {
        'categories:performance': ['error', { minScore: 0.9 }],
        'categories:accessibility': ['error', { minScore: 0.95 }],
        'categories:best-practices': ['warn', { minScore: 0.9 }],
        'categories:seo': ['warn', { minScore: 0.9 }],
        // Core Web Vitals
        'first-contentful-paint': ['error', { maxNumericValue: 2000 }],
        'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
        'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }],
        'total-blocking-time': ['error', { maxNumericValue: 300 }],
      },
    },
    upload: {
      target: 'temporary-public-storage',   // free, reports available for 7 days
    },
  },
}

Step 2: GitHub Actions

# .github/workflows/lighthouse.yml — Lighthouse CI in GitHub Actions
name: Lighthouse CI

on: [pull_request]

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

      - run: pnpm install --frozen-lockfile
      - run: pnpm build

      - name: Run Lighthouse CI
        uses: treosh/lighthouse-ci-action@v11
        with:
          configPath: './lighthouserc.js'
          uploadArtifacts: true
          temporaryPublicStorage: true

Step 3: Performance Budgets

// budget.json — Resource budgets
[
  {
    "path": "/*",
    "resourceSizes": [
      { "resourceType": "script", "budget": 300 },
      { "resourceType": "total", "budget": 500 },
      { "resourceType": "image", "budget": 200 },
      { "resourceType": "stylesheet", "budget": 50 }
    ],
    "resourceCounts": [
      { "resourceType": "third-party", "budget": 5 }
    ]
  }
]

Guidelines

• Set numberOfRuns: 3 minimum — single runs have high variance.
• Start with warn assertions, switch to error once baselines are stable.
• Test critical user paths (landing, dashboard, checkout), not every page.
• Performance budgets prevent "just one more script" — bundle size creep caught early.
• Use temporary-public-storage for free report hosting; self-host LHCI Server for history.