CI Integration

The unlighthouse beta package includes the unlighthouse-ci executable. Use Node.js 24.13.1 or newer and an installed Chrome browser in your runner.

pnpm add -D unlighthouse@beta
pnpm exec unlighthouse-ci --site https://staging.example.com --budget 80 --reporter json

The runner waits for completion, writes the export, and exits. A failed budget, failed assertion, or scan with no successful routes returns a nonzero exit code.

Configure budgets

import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'https://staging.example.com',
  ci: {
    reporter: 'json',
    budget: { performance: 80, accessibility: 90 },
    buildStatic: true,
  },
})

Run pnpm exec unlighthouse-ci to use the configured site and budget. Budgets use percentages from 1 to 100.

Reports

Exports live under the configured output directory. An explicit --reporter overrides ci.reporter. Use ci.reporterConfig.columns for expanded CSV column arrays.

Devices and cache

pnpm exec unlighthouse-ci --site https://example.com --device mobile,desktop --no-cache --reporter csv

JSON rows include device; CSV adds a final Device column. Treat (path, device) as the row identity. Read CSV columns by their header name. CI follows configured cache behavior. Use --no-cache to reset output.

Static dashboard

Use --build-static to generate a static dashboard after the scan. Publish the complete generated client directory so assets remain available.

Lighthouse CI server

Install the optional Lighthouse CI utilities before uploading raw Lighthouse results:

pnpm add -D @lhci/utils
pnpm exec unlighthouse-ci --site https://example.com --reporter lighthouseServer --lhci-host https://lhci.example.com --lhci-build-token "$LHCI_TOKEN"

Keep the build token in your runner secrets. For previous CI integrations, read Migrating to v1.