Lighthouse CI

Run Google Lighthouse on every commit. Lighthouse CI integrates web performance audits into your CI/CD pipeline, enforces Core Web Vitals budgets, and fails the build when performance regressions are detected — before they reach production.

What is Lighthouse CI?

Lighthouse CI (@lhci/cli) is the official open-source tooling for running Google Lighthouse in automated environments. While Lighthouse itself is a browser audit tool that measures performance, accessibility, SEO, and best practices, Lighthouse CI wraps it for CI pipelines — handling multi-run averaging, threshold assertions, and result storage.

By adding Lighthouse CI to your workflow, you get a hard gate on performance: if LCP exceeds 2.5s or CLS exceeds 0.1, the build fails and the PR is blocked. This makes performance a first-class engineering constraint, not an afterthought.

Key Features

• Threshold assertions — fail CI on any Lighthouse metric exceeding your budget (score, numeric, or both)
• Multi-URL support — audit multiple pages per build (homepage, product page, checkout flow)
• Statistical accuracy — run N times, use median to smooth out variance
• GitHub integration — post pass/fail status checks directly on pull requests
• Result storage — temporary public storage, self-hosted LHCI server, or custom webhook
• Dashboard — self-hosted server includes a UI for browsing historical results and diffs
• Puppeteer scripts — test authenticated pages, SPAs, and custom interactions

Installation

# Install globally or as dev dependency
npm install -g @lhci/cli
# or
npm install --save-dev @lhci/cli

# Verify
lhci --version

Configuration (lighthouserc.js)

# lighthouserc.js
module.exports = {
  ci: {
    collect: {
      url: ['https://example.com/', 'https://example.com/about'],
      numberOfRuns: 3,
    },
    assert: {
      assertions: {
        'categories:performance': ['error', { minScore: 0.9 }],
        'categories:accessibility': ['warn', { minScore: 0.9 }],
        'first-contentful-paint': ['error', { maxNumericValue: 2000 }],
        'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
        'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }],
        'total-blocking-time': ['warn', { maxNumericValue: 300 }],
      },
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
};

GitHub Actions Integration

# .github/workflows/lighthouse.yml
name: Lighthouse CI
on: [push]

jobs:
  lhci:
    name: Lighthouse
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - name: Run Lighthouse CI
        run: |
          npm install -g @lhci/[email protected]
          lhci autorun
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}

Core Web Vitals Thresholds

Self-Hosted LHCI Server

# Run via Docker
docker run -p 9001:9001 patrickhulce/lhci-server

# Or install and run with Node.js
npm install -g @lhci/server
lhci server --storage.storageMethod=sql \
  --storage.sqlDialect=sqlite \
  --storage.sqlDatabasePath=./lhci.db

Point your upload.serverBaseUrl to the server address. The server provides a web UI for browsing historical Lighthouse reports and performance trend charts.