Performance Budgets and Lighthouse CI

The plain-language idea

A performance budget is a numeric ceiling on something that affects user experience — bundle size, LCP, Total Blocking Time — that the build is not allowed to exceed. Lighthouse CI (@lhci/cli) is the tool that runs Lighthouse against your app in an automated pipeline and fails the job when a budget is broken, instead of just printing a score for a human to glance at and forget.

The reason this needs to be a CI gate and not a habit: a single "just this once" 200KB chart library, added under deadline pressure, doesn't feel like a regression to the person who added it — it feels like normal feature work. Nobody runs Lighthouse locally before every PR. A budget enforced in CI catches exactly the commit that caused the regression, with the diff still fresh, instead of surfacing as "the site feels slower lately" three months later with no idea which of two hundred commits did it.

See it in a real thing: a budget file and a CI job that enforces it

Lighthouse CI reads a config file describing what to test and what to assert against:

// lighthouserc.js
module.exports = {
  ci: {
    collect: {
      staticDistDir: "./out",
      numberOfRuns: 3,
      url: ["http://localhost/", "http://localhost/pricing"],
    },
    assert: {
      assertions: {
        "categories:performance": ["error", { minScore: 0.9 }],
        "largest-contentful-paint": ["error", { maxNumericValue: 2500 }],
        "total-blocking-time": ["error", { maxNumericValue: 200 }],
        "resource-summary:script:size": ["error", { maxNumericValue: 300000 }],
      },
    },
    upload: {
      target: "temporary-public-storage",
    },
  },
};

numberOfRuns: 3 matters more than it looks like it should — Lighthouse scores vary run to run from ordinary machine noise, and asserting against a single run means a budget check that's flaky by construction. Lighthouse CI takes the median of the three automatically, so the assertions below are checked against a stable number, not whichever run happened to land first.

Wiring it into GitHub Actions so a regression genuinely blocks the merge, not just the deploy:

# .github/workflows/lighthouse.yml
name: Lighthouse CI
on: pull_request

jobs:
  lhci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: pnpm install --frozen-lockfile
      - run: pnpm build && pnpm exec next export -o out
      - run: pnpm dlx @lhci/cli autorun

The critical detail: this runs against a production build (pnpm build), never pnpm dev. Dev mode ships unminified code, unbundled modules, and extra instrumentation — every metric it produces is wrong in the pessimistic direction, so a budget checked against dev output either never fires (masking real regressions) or fires constantly on noise unrelated to anything a reviewer can act on.

What people usually miss

Watch out

• A budget with no CI gate is just a number someone remembers, until they don't. The entire value of a performance budget is that it's enforced automatically on every PR — a budget documented in a wiki page and checked "when someone thinks of it" gives you zero actual protection against regression.
• Assert against a production build, never next dev. Dev-mode bundles are deliberately unoptimized; a budget checked against them either fires on noise (unminified code always "fails" a tight size budget) or misses genuine regressions the minified build would have exposed.
• A single Lighthouse run is not a measurement, it's a sample. Network conditions, CPU throttling emulation, and machine load all introduce real run-to-run variance — numberOfRuns: 3 (or more) and taking the median is what makes the assertion trustworthy instead of flaky.
• Bundle-size budgets and Core Web Vitals budgets catch different regressions and both matter. A team that only budgets the Lighthouse performance score can still ship a 400KB dependency that happens not to move LCP on a fast test machine, but does on a real user's mid-tier phone — asserting resource-summary:script:size directly closes that gap.

Why this matters in interviews

"Your team shipped a chart library last sprint and now LCP is failing your SLA in production — how do you make sure this doesn't happen silently again?" tests whether a candidate's answer is a process ("we should be more careful reviewing PRs") or a mechanism (a CI-enforced budget that fails the specific PR that regresses it). The strongest candidates volunteer that the check has to run against a production build and account for run-to-run variance, not just that "Lighthouse should run in CI" as a vague gesture.