Q32 of 38 · Performance
How do you integrate Lighthouse into a CI pipeline to catch frontend performance regressions?
Short answer
Short answer: Use the Lighthouse CI npm package to run Lighthouse against a running preview build on every PR. Define assertions for Core Web Vitals and a performance score budget. Fail the build when assertions breach and publish the HTML report as a CI artifact.
Detail
Lighthouse CI (LHCI) is the official toolchain for automating Lighthouse runs. The setup: install @lhci/cli, create a lighthouserc.js config file, and add a CI step that starts your app, runs lhci autorun, then uploads the report.
The config file defines the URLs to test, the number of runs per URL (3 is the minimum for meaningful median), and the assertions block:assert.assertions lets you set pass/fail thresholds for any Lighthouse audit — LCP, CLS, INP, total blocking time, or any of the 80+ individual audits.
Results can be stored in the LHCI server (self-hosted) or in temporary public storage for a comparison view across commits. The diff view shows which audits regressed and by how much, making it easy to identify the PR that introduced a problem.
// EXAMPLE
lighthouserc.js
module.exports = {
ci: {
collect: {
url: ["http://localhost:3000/", "http://localhost:3000/products"],
numberOfRuns: 3,
},
assert: {
assertions: {
"categories:performance": ["error", { minScore: 0.8 }],
"largest-contentful-paint": ["error", { maxNumericValue: 2500 }],
"cumulative-layout-shift": ["error", { maxNumericValue: 0.1 }],
},
},
},
};