Lighthouse CI Integration

# Lighthouse CI Integration

You are an expert in integrating Lighthouse CI into development workflows for automated performance testing and regression prevention.

## Key Principles
- Add Lighthouse CI to GitHub Actions
- Set meaningful performance budgets
- Block PRs on significant regressions
- Track metrics over time
- Generate actionable reports

## Lighthouse CI Setup
```bash
# Install Lighthouse CI
npm install -D @lhci/cli

# Initialize configuration
npx lhci wizard

# Run locally
npx lhci autorun
```

## Configuration File
```javascript
// lighthouserc.js
module.exports = {
  ci: {
    collect: {
      // URLs to test
      url: [
        "http://localhost:3000/",
        "http://localhost:3000/products",
        "http://localhost:3000/products/sample-product",
        "http://localhost:3000/checkout",
      ],
      
      // Start server before running
      startServerCommand: "npm run start",
      startServerReadyPattern: "ready on",
      startServerReadyTimeout: 30000,
      
      // Number of runs per URL
      numberOfRuns: 3,
      
      // Chrome settings
      settings: {
        preset: "desktop", // or "mobile"
        throttling: {
          cpuSlowdownMultiplier: 1,
        },
        // Skip specific audits
        skipAudits: ["uses-http2"],
        // Custom headers
        extraHeaders: JSON.stringify({
          "Authorization": "Bearer test-token",
        }),
      },
    },
    
    assert: {
      preset: "lighthouse:recommended",
      
      assertions: {
        // Performance score
        "categories:performance": ["error", { minScore: 0.9 }],
        "categories:accessibility": ["error", { minScore: 0.95 }],
        "categories:best-practices": ["error", { minScore: 0.9 }],
        "categories:seo": ["error", { minScore: 0.9 }],
        
        // Core Web Vitals
        "largest-contentful-paint": ["error", { maxNumericValue: 2500 }],
        "cumulative-layout-shift": ["error", { maxNumericValue: 0.1 }],
        "total-blocking-time": ["error", { maxNumericValue: 300 }],
        "first-contentful-paint": ["warn", { maxNumericValue: 1800 }],
        "speed-index": ["warn", { maxNumericValue: 3400 }],
        "interactive": ["warn", { maxNumericValue: 3800 }],
        
        // Resource budgets
        "resource-summary:script:size": ["error", { maxNumericValue: 300000 }],
        "resource-summary:stylesheet:size": ["error", { maxNumericValue: 100000 }],
        "resource-summary:image:size": ["warn", { maxNumericValue: 500000 }],
        "resource-summary:total:size": ["error", { maxNumericValue: 1500000 }],
        
        // Specific audits
        "uses-responsive-images": "warn",
        "offscreen-images": "warn",
        "render-blocking-resources": "warn",
        "unused-javascript": "warn",
        "uses-text-compression": "error",
        "uses-long-cache-ttl": "warn",
      },
    },
    
    upload: {
      // Upload to Lighthouse CI Server
      target: "lhci",
      serverBaseUrl: "https://lhci.example.com",
      token: process.env.LHCI_TOKEN,
      
      // Or use temporary public storage
      // target: "temporary-public-storage",
    },
  },
};
```

## GitHub Actions Workflow
```yaml
# .github/workflows/lighthouse.yml
name: Lighthouse CI

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build application
        run: npm run build
        env:
          NODE_ENV: production
      
      - name: Run Lighthouse CI
        uses: treosh/lighthouse-ci-action@v11
        with:
          configPath: "./lighthouserc.js"
          uploadArtifacts: true
          temporaryPublicStorage: true
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
      
      - name: Upload Lighthouse Report
        uses: actions/upload-artifact@v4
        with:
          name: lighthouse-report
          path: .lighthouseci/
          retention-days: 30

  # Comparison job for PRs
  compare:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    needs: lighthouse
    
    steps:
      - name: Download PR artifacts
        uses: actions/download-artifact@v4
        with:
          name: lighthouse-report
          path: ./pr-report
      
      - name: Compare with main
        run: |
          # Custom comparison script
          node scripts/compare-lighthouse.js
      
      - name: Comment on PR
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const report = JSON.parse(fs.readFileSync('./comparison.json'));
            
            const body = `## Lighthouse Report
            
            | Metric | Main | PR | Diff |
            |--------|------|----|----|
            | Performance | ${report.main.performance} | ${report.pr.performance} | ${report.diff.performance} |
            | LCP | ${report.main.lcp}ms | ${report.pr.lcp}ms | ${report.diff.lcp}ms |
            | CLS | ${report.main.cls} | ${report.pr.cls} | ${report.diff.cls} |
            `;
            
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: body
            });
```

## Custom Performance Budget
```javascript
// budget.json
[
  {
    "path": "/*",
    "resourceSizes": [
      { "resourceType": "script", "budget": 300 },
      { "resourceType": "stylesheet", "budget": 100 },
      { "resourceType": "image", "budget": 500 },
      { "resourceType": "font", "budget": 100 },
      { "resourceType": "total", "budget": 1500 }
    ],
    "resourceCounts": [
      { "resourceType": "script", "budget": 15 },
      { "resourceType": "stylesheet", "budget": 5 },
      { "resourceType": "image", "budget": 30 }
    ],
    "timings": [
      { "metric": "first-contentful-paint", "budget": 1800 },
      { "metric": "largest-contentful-paint", "budget": 2500 },
      { "metric": "cumulative-layout-shift", "budget": 0.1 },
      { "metric": "total-blocking-time", "budget": 300 }
    ]
  },
  {
    "path": "/checkout",
    "timings": [
      { "metric": "interactive", "budget": 3000 }
    ]
  }
]
```

## Lighthouse CI Server Setup
```bash
# Docker deployment
docker run -d \
  --name lhci-server \
  -p 9001:9001 \
  -e LHCI_NO_LIGHTHOUSERC=true \
  -v lhci-data:/data \
  patrickhulce/lhci-server

# Create project and get token
docker exec -it lhci-server lhci wizard
```

## Tracking Reports Over Time
```typescript
// scripts/analyze-trends.ts
import { getClient } from "@lhci/utils/src/api-client";

async function analyzeTrends() {
  const client = getClient({
    rootURL: "https://lhci.example.com",
    token: process.env.LHCI_TOKEN,
  });
  
  const project = await client.findProjectBySlug("my-app");
  const builds = await client.getBuilds(project.id, { limit: 30 });
  
  // Calculate trends
  const performanceScores = builds.map(b => b.performanceScore);
  const averageScore = performanceScores.reduce((a, b) => a + b) / performanceScores.length;
  const trend = performanceScores[0] - performanceScores[performanceScores.length - 1];
  
  console.log(`Average Performance: ${averageScore.toFixed(2)}`);
  console.log(`30-day Trend: ${trend > 0 ? "+" : ""}${trend.toFixed(2)}`);
  
  // Alert on degradation
  if (trend < -5) {
    await sendSlackAlert({
      message: `Performance degradation detected: ${trend.toFixed(2)} points over 30 days`,
    });
  }
}
```

## Best Practices
- Run Lighthouse CI on every PR
- Set appropriate thresholds for your app
- Track metrics over time for trend analysis
- Use performance budgets to prevent bloat
- Compare against main branch baseline
- Generate reports for stakeholder visibility