Add Lighthouse CI for performance regression testing

[michaeldistel]

Problem

No automated performance testing:

• Performance regressions invisible
• Manual Lighthouse audits only
• No PR performance checks
• Can't enforce performance budgets

Solution

Integrate Lighthouse CI into GitHub Actions:

pnpm add -D @lhci/cli

Configuration

// lighthouserc.js
module.exports = {
  ci: {
    collect: {
      staticDistDir: './build',
      url: [
        'http://localhost/index.html',
        'http://localhost/docs/index.html',
        'http://localhost/docs/syntax/index.html'
      ],
      numberOfRuns: 3
    },
    assert: {
      preset: 'lighthouse:recommended',
      assertions: {
        '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 }],
        
        // Performance budgets
        '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 }],
        
        // Resource budgets
        'resource-summary:script:size': ['error', { maxNumericValue: 300000 }], // 300KB
        'resource-summary:stylesheet:size': ['error', { maxNumericValue: 50000 }], // 50KB
        'resource-summary:image:size': ['error', { maxNumericValue: 500000 }] // 500KB
      }
    },
    upload: {
      target: 'temporary-public-storage'
    }
  }
};

GitHub Actions Workflow

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

on:
  pull_request:
  push:
    branches: [main]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
      
      - name: Install dependencies
        run: pnpm install
      
      - name: Build
        run: pnpm build:prod
      
      - name: Run Lighthouse CI
        run: |
          pnpm dlx @lhci/cli@0.13.x autorun
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
      
      - name: Upload results
        uses: actions/upload-artifact@v4
        with:
          name: lighthouse-results
          path: .lighthouseci

PR Comments

Lighthouse CI can comment on PRs with results:

upload: {
  target: 'temporary-public-storage',
  githubAppToken: process.env.LHCI_GITHUB_APP_TOKEN
}

Performance Budgets

Current Baseline

• Performance: 90+
• Accessibility: 95+
• Best Practices: 100
• SEO: 100

Budgets

• FCP: <2s
• LCP: <2.5s
• TBT: <300ms
• CLS: <0.1
• Scripts: <300KB
• Stylesheets: <50KB
• Images: <500KB

LHCI Server (Optional)

Self-host Lighthouse CI server for historical data:

docker run -p 9001:9001 -v lhci-data:/data patrickhulce/lhci-server

Success Criteria

• Lighthouse CI runs on every PR
• Fails if performance <90
• Budgets enforced
• Results commented on PR
• Historical trends tracked
• No regressions deployed