Frontend Beauty
ESC

Type to search the knowledge base.

Performance Budgets in CI

Encode LCP/size budgets in CI with Lighthouse CI or size-limit so regressions fail pull requests.

intermediate3 min read
  • performance
  • ci
  • budgets
  • lighthouse
  • automation

Performance budgets only work when they fail the build. CI budgets turn LCP, JS kilobytes, and third-party counts into merge gates so regressions don’t wait for quarterly CWV reviews.

Docs: Performance budgets 101, Lighthouse CI, web.dev budgets.

What to enforce

Budget type Example
Resource size JS ≤ 200KB compressed on /
Count ≤ 50 requests on /
Lab timing LCP ≤ 2500ms on throttled CI
Score floor Perf score ≥ 0.8 (noisy — prefer timings)
Third-party Known tag list only

Align with product SLOs; start slightly looser than ideal to avoid cry-wolf, then tighten.

Lighthouse CI sketch

// lighthouserc.js
module.exports = {
  ci: {
    collect: { url: ['http://localhost:3000/'], numberOfRuns: 3 },
    assert: {
      assertions: {
        'categories:performance': ['error', { minScore: 0.8 }],
        'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
        'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }],
        'total-byte-weight': ['warn', { maxNumericValue: 800000 }],
      },
    },
  },
};

Use median of multiple runs. Pin Lighthouse version.

Size-limit / bundlesize

// package.json idea
"size-limit": [
  { "path": "dist/assets/index-*.js", "limit": "180 KB" }
]

Fast PR signal before full browser CI.

Stability tactics

  1. Block network to non-essential third parties in lab CI or budget them explicitly.
  2. Seed same auth state.
  3. Use production build, not dev.
  4. Retry flaky runs; fail on consistent breach.
  5. Separate mobile emulation vs desktop configs.

Process

  • Budget owners per surface (home, PDP, checkout).
  • Temporary waivers with expiry issue links.
  • Field CWV dashboard still required — CI is lab gate — lab vs field.

Interview out-loud

“CI budgets assert size and lab timings on production builds so PRs can’t silently regress. I prefer LCP/CLS numeric asserts plus bundle size-limit, median of multiple Lighthouse runs, and field verification after merge.”

How this shows up in interviews

Be ready to define the metric or technique in one sentence, name one measurement approach (DevTools panel, web-vitals, or headers), and cite a concrete fix you would try first. Walk through a before/after: what the waterfall or flame chart showed, what you changed, and which percentile moved. Mention a tradeoff (complexity, caching correctness, or third-party business constraints) so the answer doesn’t sound like a blog checklist.

Production guardrails

Ship behind a flag when the change is risky, watch field p75 for the affected template for at least a few days, and keep a rollback path. Pair lab verification (throttled Performance/Network) with RUM so you don’t celebrate a Lighthouse-only win. Document the owner of any ongoing budget or third-party exception.

Further depth

Teams often under-invest in this topic until an incident or CWV regression. Schedule a one-hour drill: reproduce the failure mode in DevTools, list the top three mitigations for your stack, and file tickets with owners. Revisit after the next major feature that touches networking, rendering, auth, or third parties — those are the moments regressions land. Keep primary documentation links in the runbook so on-call is not searching chat history at 2am.

Concrete artifacts to leave behind: a short architecture note, a CI assertion or header snapshot, and a dashboard panel (lab or field) that would have caught the last bug. Teaching the rest of the team the mental model matters as much as the one-line fix.

Further reading

Related guides