Block PRs that fail Core Web Vitals budgets with Lighthouse CI

Frontend Lighthouse describes a portable Lighthouse CI performance gate for production frontend builds. It combines a single lighthouserc.cjs configuration, explicit Core Web Vitals budgets and category score floors, repeated runs with median aggregation, a CI workflow that blocks pull requests, and report artifacts for debugging. It is a performance gate, not a component library or visual style. The source positions it alongside frontend SEO and architecture work: metadata is supplied elsewhere, while this gate checks that the production site ships quickly.

Use it when adding Lighthouse CI to a web application, setting LCP, CLS, and TBT budgets, setting performance, SEO, accessibility, and best-practices floors, debugging unstable audit runs, or making reports available as CI artifacts. Run Lighthouse against the optimized production build, not a development server. Median aggregation across three or more runs reduces sensitivity to per-run jitter such as cold caches and CI noise.

Lighthouse is a lab signal. It does not replace field monitoring of real-user metrics, and a passing score does not prove business-critical flows, visual correctness, or backend availability. Budgets need tuning for the actual route, hosting platform, and device and network assumptions. Do not continually raise thresholds just to make CI pass; record the reason for any threshold change and prefer fixing the regression.

Inputs include the app routes under test, production build and start commands, framework readiness log, mobile or desktop form factor, run count, category selection, and named thresholds. The documented mobile targets are LCP at or below 2500 ms, CLS at or below 0.1, and TBT at or below 200 ms as a lab proxy for INP. The experimental interaction-to-next-paint audit is a warning because it is not available in every Lighthouse build. Category floors are performance 0.9, SEO 0.95, accessibility 0.95, and best practices 0.9. Use error severity for required contracts and warning severity for environment-dependent or aspirational audits.

The configuration uses CommonJS so it can load without ESM or TypeScript transpilation. Each budget is a named constant with units and a comment. The collection settings use the production server and a mobile preset by default, with desktop optionally selected through an environment variable. It collects only gated categories, uses at least three runs, and asserts on the median run. The report upload target is the local filesystem, with output in .lighthouseci.

Guidance covers installing @lhci/cli, adding an lhci package script, and running build then Lighthouse CI locally to reproduce the workflow. GitHub Actions runs on pull requests that touch the app or workflow, installs dependencies, builds the app, runs the gate, and uploads reports with an always-run step, including on failure. The Node and pnpm versions should match those pinned by the repository.

Framework examples include Next.js, Remix, Astro, SvelteKit, and Vite SPA. The config is framework-neutral except for its start-server command and readiness pattern. Static output can instead use staticDistDir. The source install command is:

pnpm add -D @lhci/cli        # or npm i -D / yarn add -D

For flaky LCP or TBT, try five runs while retaining median aggregation, and check for competing CPU work. For a server-readiness timeout, match the readiness pattern to the framework log and adjust the timeout. For a real regression, inspect the uploaded audit report and address the cited cause, such as an oversized image, render-blocking JavaScript, or layout shift from unsized media, rather than increasing the budget. Run mobile and desktop form factors when they diverge; mobile is the stricter default.

The documented file set is a CommonJS lighthouserc.cjs, an lhci package script, a pull-request workflow, and the @lhci/cli development dependency. Keep the production start command, readiness message, and pinned Node and pnpm versions aligned with the application. The workflow should build before collecting audits and upload .lighthouseci reports in an always-run step so a failed assertion still leaves evidence. Scope pull-request triggers to application and workflow changes. For static output, configure the static distribution directory instead of starting a server.

When reviewing changes, verify the budget constants carry units and comments, only gated categories are collected, and median aggregation uses at least three runs. Required audits should have error severity while the experimental interaction-to-next-paint audit stays a warning. Treat a Lighthouse pass as a lab check only; retain real-user monitoring and separate checks for application behavior and visual correctness.

Frontend developers and platform engineers can use the skill to make performance budgets repeatable locally and in CI. Reviewers can check that all thresholds are documented, production output is measured, the median of at least three runs is asserted, the experimental INP audit remains a warning, CI triggers on config changes, and reports upload even when the gate fails. The approach yields an auditable performance contract with artifacts for investigation.