perf/lighthouse-ci

Why

A single Lighthouse run varies with CPU load, network and extensions, so a CI gate on one run fails at random and teaches people to ignore it. A gate at 100 is the same: the curve makes the last points almost unreachable and the score says nothing about real visitors.

Fix

Use @lhci/cli with numberOfRuns: 3 or more (the median is used), assert on the metrics that matter (largest-contentful-paint, cumulative-layout-shift, total-blocking-time) and on category scores with warn below and error well below your target, and test the URLs of each page type. Run on a dedicated, quiet runner; compare with the previous main build rather than an absolute number when you can.

Examples

{
  "ci": {
    "collect": { "url": ["http://localhost:4173/", "http://localhost:4173/pricing"], "numberOfRuns": 3 },
    "assert": { "assertions": {
      "categories:performance": ["warn", { "minScore": 0.9 }],
      "categories:accessibility": ["error", { "minScore": 0.95 }],
      "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
      "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }]
    } }
  }
}

Sources

• Lighthouse CI, configuration (collect.numberOfRuns, assert)
• Chrome for Developers, Lighthouse performance scoring (variability)

Read it in the terminal

npx github:dawidolko/frontend-skills explain perf/lighthouse-ci