Lighthouse CI Setup for Automated Performance Checks

Lighthouse CI: Automatic Performance Checks

Lighthouse CI runs Google Lighthouse on every PR in CI/CD and blocks merge if Performance, Accessibility or SEO score drops below threshold.

Installation and Setup

npm install --save-dev @lhci/cli @lhci/utils

// lighthouserc.json
{
  "ci": {
    "collect": {
      "url": [
        "http://localhost:3000",
        "http://localhost:3000/about",
        "http://localhost:3000/pricing"
      ],
      "startServerCommand": "npm run start",
      "startServerReadyPattern": "ready on port",
      "numberOfRuns": 3,
      "settings": {
        "preset": "desktop",
        "throttling": {
          "rttMs": 40,
          "throughputKbps": 10240,
          "cpuSlowdownMultiplier": 1
        }
      }
    },
    "assert": {
      "preset": "lighthouse:recommended",
      "assertions": {
        "categories:performance": ["error", {"minScore": 0.9}],
        "categories:accessibility": ["error", {"minScore": 0.9}],
        "categories:best-practices": ["warn", {"minScore": 0.9}],
        "categories:seo": ["error", {"minScore": 0.9}],
        "first-contentful-paint": ["warn", {"maxNumericValue": 2000}],
        "largest-contentful-paint": ["error", {"maxNumericValue": 2500}],
        "total-blocking-time": ["error", {"maxNumericValue": 300}],
        "cumulative-layout-shift": ["error", {"maxNumericValue": 0.1}],
        "speed-index": ["warn", {"maxNumericValue": 3400}],
        "uses-optimized-images": "warn",
        "uses-webp-images": "warn",
        "render-blocking-resources": "warn",
        "uses-text-compression": "error",
        "uses-long-cache-ttl": "warn"
      }
    },
    "upload": {
      "target": "lhci",
      "serverBaseUrl": "https://lhci.mysite.com",
      "token": "${LHCI_TOKEN}"
    }
  }
}

GitHub Actions

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

on:
  pull_request:
    branches: [main]

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

      - run: npm ci
      - run: npm run build

      - name: Run Lighthouse CI
        run: |
          npm install -g @lhci/cli
          lhci autorun
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
          LHCI_TOKEN: ${{ secrets.LHCI_TOKEN }}

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

LHCI Server: Save History

# Docker Compose: LHCI Server for storing results
services:
  lhci-server:
    image: patrickhulce/lhci-server:latest
    environment:
      LHCI_STORAGE__SQL_DATABASE_URL: "postgresql://lhci:secret@db/lhci"
    ports:
      - "9001:9001"
    volumes:
      - lhci_data:/data

  db:
    image: postgres:15
    environment:
      POSTGRES_DB: lhci
      POSTGRES_USER: lhci
      POSTGRES_PASSWORD: secret

Setup Lighthouse CI with LHCI Server and GitHub Actions — 1–2 working days.