Block PRs that fail Core Web Vitals budgets with Lighthouse CI

A portable CI performance gate for web apps - a Lighthouse CI configuration plus a GitHub Actions workflow that blocks pull requests unless the production build meets explicit Core Web Vitals budgets and category score floors. It pairs with the frontend-seo skill (SEO writes the metadata, Lighthouse proves it ships fast) and frontend-architecture. Five core ideas: one lighthouserc.cjs holds every budget and assertion as named constants (never magic numbers); the gate always runs against the production build+start output, never the dev server; median-of-3+ runs (aggregationMethod "median-run") kills per-run flakiness from cold caches or CI noise; budgets encode Google's "good" Core Web Vitals thresholds (LCP <= 2500ms, INP <= 200ms gated via the TBT lab proxy since INP has no direct lab audit, CLS <= 0.1), plus category floors (performance >= 0.9, SEO and accessibility >= 0.95, best-practices >= 0.9); and a GitHub Action blocks every PR touching the app, always uploading HTML/JSON reports as artifacts (even on failure) so a red check is debuggable. The experimental interaction-to-next-paint audit is asserted as a warn, not an error, since it's missing in some Lighthouse builds. The config's collect step runs the production server on a fixed port with a startServerReadyPattern matching the framework's ready log line, and onlyCategories is scoped to exactly what's gated (performance, seo, accessibility, best-practices - skipping PWA noise). A framework-adapter table covers the two settings that actually vary by framework - startServerCommand and startServerReadyPattern - for Next.js ("Ready in"), Remix, Astro (SSR or static serve), SvelteKit ("Listening on"), and Vite SPA ("Local:"); fully static output can skip the server entirely via collect.staticDistDir. Debugging guidance covers flaky LCP/TBT (raise numberOfRuns), spurious interaction-to-next-paint errors (should be warn not error), server-not-ready timeouts (fix the ready pattern and timeout), and real regressions (read the report's Opportunities/Diagnostics and fix the cause - don't just bump the budget). A conventions checklist enforces all of this in review, ending with the rule that budgets tighten over time and only loosen with a recorded reason.

Use it when adding a Lighthouse CI performance gate to a web app, setting Core Web Vitals budgets for LCP/CLS/TBT, configuring category score floors, or debugging flaky Lighthouse runs and making reports visible as CI artifacts.

Given URLs to audit and a framework's start command, it produces a lighthouserc.cjs with named budget constants, a package.json lhci script, and a GitHub Actions workflow that builds, serves, audits, and uploads reports - failing the PR check if any budget or category floor is exceeded on the median run.

pnpm add -D @lhci/cli

Runs via lhci autorun (collect -> assert -> upload) both locally and in CI, uploading reports to the filesystem rather than an external LHCI server; framework-neutral except for the server start command and ready-log pattern.

Frontend teams who want Core Web Vitals and Lighthouse category scores enforced as a hard CI gate rather than tracked informally - blocking regressions before merge instead of discovering them after a page has already shipped slow.