Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Portable skill — readable by Claude Code, OpenCode, Codex, Cursor, Windsurf, and others.
This skill describes a CI performance gate — a Lighthouse CI config plus a workflow — not a
component library or a visual style. It pairs with the frontend-seo and
frontend-architecture skills: SEO writes the metadata, Lighthouse proves it ships fast.
The goal: every pull request is blocked unless the production build meets explicit Core Web
Vitals budgets and category score floors. Budgets live in onelighthouserc.cjs, runs are
median-of-N so the gate doesn't flake, and the same config runs locally and in CI.
When to Use This Skill
Use when adding a Lighthouse CI performance gate to a web app.
Use when setting Core Web Vitals budgets for LCP, CLS, and TBT as the lab proxy for INP.
Use when configuring category score floors for performance, SEO, accessibility, and best practices.
Use when debugging flaky Lighthouse runs or making reports visible as CI artifacts.
0. The five core ideas
One config, one source of truth. All budgets and assertions live in a single lighthouserc.cjs. Named constants for each budget — no magic numbers buried in assertion objects.
Gate the production build, never dev. Lighthouse runs against build + start (the real, optimized output). Dev-server numbers are meaningless for a budget.
Median-of-N kills flakiness. Run 3+ times and assert on the median run, so per-run jitter (cold caches, CI noise) never red-flags a healthy build.
Budgets encode Google's "good" thresholds. LCP ≤ 2500 ms, INP ≤ 200 ms (gated via the TBT lab proxy), CLS ≤ 0.1 — the values that earn green scores, not "needs improvement".
Blocking in CI, visible as artifacts. A GitHub Action runs the gate on every PR touching the app and uploads the HTML/JSON reports so failures are debuggable.
.cjs (CommonJS) so it loads without ESM/TS transpilation. Every budget is a named constant
with a comment explaining the threshold — never a bare number inside an assertion.
/**
* Lighthouse CI configuration — Core Web Vitals budgets for the marketing surface.
*
* Enforces Google's mobile "good" CWV thresholds:
* - Largest Contentful Paint (LCP) ≤ 2500 ms
* - Cumulative Layout Shift (CLS) ≤ 0.1
* - Interaction to Next Paint (INP) ≤ 200 ms
*
* INP is a *field* metric with no direct lab audit, so in the lab we gate on
* Total Blocking Time (TBT) — Lighthouse's recommended lab proxy — at the same
* budget, and assert the experimental INP audit directly as a warning where the
* build exposes it.
*
* Collection runs against the *production* server (build + start) on Lighthouse's
* default mobile (Moto G4 / slow 4G) emulation.
*//** The fixed port the production server is started on for the audit. */constPORT = 3100;
constBASE_URL = `http://localhost:${PORT}`;
/** Pages whose budgets are enforced in CI. */constMARKETING_URLS = [`${BASE_URL}/`];
/**
* Core Web Vitals budgets on mobile — Google's "good" thresholds.
* These are the values that earn the best Lighthouse scores.
*/constLCP_BUDGET_MS = 2500; // goodconstINP_BUDGET_MS = 200; // good (TBT lab proxy)constCLS_BUDGET = 0.1; // goodmodule.exports = {
ci: {
collect: {
// Build is run separately in CI; here we only serve the production output.startServerCommand: `pnpm start --port ${PORT}`,
startServerReadyPattern: "Ready in", // framework's "server ready" log linestartServerReadyTimeout: 120000,
url: MARKETING_URLS,
// Median of multiple runs keeps the gate stable against per-run jitter.numberOfRuns: 3,
settings: {
// Default mobile emulation; opt into desktop via env for a second run.preset:
process.env.LHCI_FORM_FACTOR === "desktop" ? "desktop" : undefined,
// Only gate the categories we care about; skip PWA category noise.onlyCategories: [
"performance",
"seo",
"accessibility",
"best-practices",
],
},
},
assert: {
// Median across runs is the value compared against each budget.aggregationMethod: "median-run",
assertions: {
// --- Core Web Vitals budgets (the contract) ---------------------"largest-contentful-paint": [
"error",
{ maxNumericValue: LCP_BUDGET_MS },
],
"cumulative-layout-shift": ["error", { maxNumericValue: CLS_BUDGET }],
"total-blocking-time": ["error", { maxNumericValue: INP_BUDGET_MS }],
// Direct INP audit where the Lighthouse build exposes it (else ignored)."interaction-to-next-paint": [
"warn",
{ maxNumericValue: INP_BUDGET_MS },
],
// --- Category floors (target top Lighthouse scores) -------------"categories:performance": ["error", { minScore: 0.9 }],
"categories:seo": ["error", { minScore: 0.95 }],
"categories:accessibility": ["error", { minScore: 0.95 }],
"categories:best-practices": ["error", { minScore: 0.9 }],
},
},
upload: {
// Keep reports in the CI run's filesystem; no external LHCI server.target: "filesystem",
outputDir: "./.lighthouseci",
},
},
};
Hard rules:
Every budget is a named constant with a unit in its name (LCP_BUDGET_MS) and a comment.
aggregationMethod: "median-run" is non-negotiable — single-run gates flake constantly.
numberOfRuns ≥ 3 (odd numbers give a clean median).
Assert on TBT for INP in the lab; treat the experimental interaction-to-next-paint audit as a warn, not an error (it isn't present in every Lighthouse build).
Keep onlyCategories to exactly what you gate — fewer audits, faster, less noise.
3. Choosing budget severity and thresholds
Audit / category
Severity
Threshold
Why
largest-contentful-paint
error
≤ 2500 ms
Google "good" LCP
cumulative-layout-shift
error
≤ 0.1
Google "good" CLS
total-blocking-time
error
≤ 200 ms
INP lab proxy
interaction-to-next-paint
warn
≤ 200 ms
not in all builds; don't hard-fail on a missing audit
categories:performance
error
≥ 0.9
top (green) band
categories:seo
error
≥ 0.95
SEO is cheap to keep perfect
categories:accessibility
error
≥ 0.95
a11y regressions must block
categories:best-practices
error
≥ 0.9
green band
Use error for contracts that must hold and warn for audits that are environment-dependent or
aspirational. Start strict and only loosen with a recorded reason — a budget you keep raising
to make CI pass is a budget that no longer protects anything.
Runs on PRs that touch the app or the workflow itself. Builds the production output, runs the
gate, and always uploads the reports (even on failure) so a red check is debuggable.
name:LighthouseCWVon:pull_request:branches: [main]
paths:-"apps/web/**"-".github/workflows/lighthouse.yml"permissions:contents:readjobs:lighthouse:name:LighthouseCWV(marketingpages)runs-on:ubuntu-latestdefaults:run:working-directory:apps/websteps:-uses:actions/checkout@v4-name:Setuppnpmuses:pnpm/action-setup@v4# version comes from root package.json packageManager-name:SetupNodeuses:actions/setup-node@v4with:node-version:22cache:pnpm-name:Installdependenciesworking-directory:.run:pnpminstall--frozen-lockfile-name:Buildwebapprun:pnpmbuild# build + start the production server, run Lighthouse on mobile emulation,# fail the job if any budget in lighthouserc.cjs is exceeded.-name:RunLighthouseCIrun:pnpmlhci-name:UploadLighthousereportsif:always()uses:actions/upload-artifact@v4with:name:lighthouse-reportspath:apps/web/.lighthouseciif-no-files-found:ignore
Hard rules:
Trigger on the app path and the workflow file so config changes are self-testing.
if: always() on the upload step — you need the report most when the gate fails.
Gate on the production build (pnpm build then the start server in collect).
Match the CI Node/pnpm versions to the repo's pinned versions to avoid lockfile drift.
6. Framework adapters
The config is framework-neutral except startServerCommand and startServerReadyPattern.
Framework
startServerCommand
startServerReadyPattern
Next.js
pnpm start --port 3100 (after next build)
"Ready in"
Remix
pnpm start (serve the built app)
server's listening log line
Astro
node ./dist/server/entry.mjs (SSR) or npx serve dist (static)
the adapter's ready line / serve's URL line
SvelteKit
node build (node adapter)
"Listening on"
Vite SPA
npx vite preview --port 3100
"Local:"
For purely static output you can skip the server and point collect.staticDistDir at the build
folder instead of startServerCommand — Lighthouse serves it internally.
7. Debugging failing or flaky runs
Flaky LCP/TBT → raise numberOfRuns (5), confirm median-run, and make sure nothing else is competing for CPU on the runner.
interaction-to-next-paint errors → it should be warn, not error; the audit is missing in some Lighthouse versions.
"server not ready" timeout → fix startServerReadyPattern to match the framework's actual ready log, and raise startServerReadyTimeout.
Real regressions → open the uploaded report artifact, read the failed audit's "Opportunities"/"Diagnostics", fix the cause (oversized image, render-blocking JS, layout shift from unsized media) — don't just bump the budget.
Desktop vs mobile divergence → run both form factors; mobile is the stricter gate and should be the default.
8. Conventions checklist (enforce in review)
All budgets are named constants with units and comments — no magic numbers in assertions.
Gate runs against the production build, never the dev server.
aggregationMethod: "median-run" with numberOfRuns ≥ 3.
CWV budgets at Google "good" thresholds (LCP ≤ 2500, TBT ≤ 200, CLS ≤ 0.1).
INP gated via TBT (error); experimental INP audit is warn.
Category floors set as error (perf ≥ 0.9, SEO/a11y ≥ 0.95, best-practices ≥ 0.9).
onlyCategories lists exactly the gated categories.
CI triggers on the app path and the workflow file; reports upload with if: always().
Local pnpm lhci reproduces the CI run.
Budgets are tightened over time, loosened only with a recorded reason.
9. How to apply this skill
Adding the gate to a project: install @lhci/cli, drop in lighthouserc.cjs with your URLs
and startServerCommand, add the lhci script, and add the workflow. Run pnpm build && pnpm lhci
locally to confirm it passes before opening a PR.
Adding a page to the gate: append its URL to MARKETING_URLS (or a second URL array). Each URL
is audited independently against the same budgets.
Tuning budgets: change the named constant, not the assertion. Record why in the comment. Prefer
fixing the regression over raising the budget.
Reviewing performance: run the checklist in §8. The highest-value catches are a gate that runs
against the dev server (meaningless numbers) and single-run assertions (chronic flakiness).
Publishing / installing this skill
This skill follows the Anthropic SKILL.md format and is portable across agents.
Keep it under skills/frontend-lighthouse/SKILL.md in a public GitHub repo.
Keep the frontmatter name and high-signal description — discovery indexes match against it.
