Performance Budgets and Lighthouse CI

Static sites start fast and get slower one pull request at a time. An analytics snippet here, a web font weight there, a hero image someone forgot to resize, a component library imported whole for one button — none of them looks like a regression in review, and together they turn a site that scored 100 into one that fails Core Web Vitals on mobile. The only reliable defence is to make performance a check that runs on every change and fails when a limit is crossed, exactly like a test.

This topic covers that defence end to end: choosing budgets, running Lighthouse CI against preview deploys, keeping results stable enough to trust, tracking bundle size per pull request, and checking lab numbers against field data. It sits inside Performance Optimization & Core Web Vitals for SSGs, and it is the enforcement layer for everything else in that section — the LCP, CLS and hydration work only stays done if something checks it.

Choosing What to Budget

A useful budget has three kinds of limit, because each catches a different class of regression.

Byte budgets limit what ships: total JavaScript, total CSS, image bytes on the page, web font bytes, request count. They are deterministic — the same build always produces the same numbers — so they never fail from noise. They catch the most common regressions directly: a new dependency, an unoptimised image, an extra font weight.

Timing budgets limit what the reader experiences in the lab: Largest Contentful Paint, Total Blocking Time (the lab proxy for INP), Cumulative Layout Shift, Speed Index. They catch problems bytes miss, such as a render-blocking stylesheet or a script that runs a long task, but they vary between runs and need care — see Reducing Lighthouse Score Variance in CI.

Rule-based assertions check Lighthouse audits pass: images have explicit dimensions, text stays visible during font load, no unused preloads, no legacy JavaScript. They catch classes of mistake rather than amounts.

A starting budget for a content-focused static site, derived from what a well-built Astro, Eleventy or Hugo site actually ships:

Set these from your current numbers, not from aspiration. A budget the site already fails is a budget the team learns to ignore. Start at current values plus a small margin, fix regressions as they appear, and tighten each quarter. Writing a Performance Budget That Fails Builds turns this table into a working configuration.

Running Lighthouse CI on Preview Deploys

Lighthouse CI (@lhci/cli) runs Lighthouse against a set of URLs, asserts against a budget, and uploads reports. For a static site, run it against the preview deploy, not a local server: the preview has the real CDN, compression, caching headers and redirects, all of which affect the numbers.

// lighthouserc.js
module.exports = {
  ci: {
    collect: {
      url: [
        `${process.env.PREVIEW_URL}/`,
        `${process.env.PREVIEW_URL}/guides/`,
        `${process.env.PREVIEW_URL}/guides/deploying-hugo/`,
        `${process.env.PREVIEW_URL}/blog/2026/cache-headers/`,
        `${process.env.PREVIEW_URL}/reference/config/`,
      ],
      numberOfRuns: 3,
      settings: { preset: 'desktop' === process.env.LH_PRESET ? 'desktop' : undefined },
    },
    assert: {
      assertions: {
        'resource-summary:script:size': ['error', { maxNumericValue: 153600 }],
        'largest-contentful-paint': ['error', { maxNumericValue: 2500, aggregationMethod: 'median' }],
        'total-blocking-time': ['warn', { maxNumericValue: 150, aggregationMethod: 'median' }],
        'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }],
        'unsized-images': 'error',
        'font-display': 'error',
      },
    },
    upload: { target: 'temporary-public-storage' },
  },
};

One URL per template is enough. Pages built from the same layout share the same assets and structure, so testing twenty blog posts tells you nothing that one does not. The step-by-step setup, including the GitHub Actions wiring and status checks, is in Setting Up Lighthouse CI for a Static Site.

Making Results Trustworthy

A performance check that fails at random gets muted within a week. Three sources of noise matter on CI runners: CPU contention from other jobs on the same host, network variation between the runner and the preview host, and Lighthouse's own simulated throttling, which extrapolates from an unthrottled trace.

On a GitHub Actions ubuntu-latest runner, ten consecutive single runs of the same page produced LCP values from 1.6 to 2.4 seconds and TBT from 40 to 210 ms. With three runs and the median, the spread across ten repetitions narrowed to 1.8–2.0 seconds and 60–110 ms — tight enough to set a threshold on.

The practical rules: median of three to five runs; byte budgets as error, timing budgets as warn until you have a month of data showing their spread; and assertions on the specific metrics rather than the composite score. The deeper treatment, including running on a dedicated runner and pinning Chrome versions, is in Reducing Lighthouse Score Variance in CI.

Tracking Bundle Size per Pull Request

Lighthouse measures pages; bundle-size tracking measures the build output directly and is faster, cheaper and completely deterministic. Tools such as size-limit or a twenty-line script comparing the dist/ asset sizes against the base branch post a comment on each pull request showing exactly what grew and by how much:

Asset changes vs main
  _astro/Search.3f9a.js     +18.4 KB  (new)       ⚠
  _astro/index.c21e.css      +0.6 KB
  Total JS (gzip)            41.2 KB → 59.6 KB    ⚠ over 50 KB warn

This catches the dependency-added-for-one-function regression within seconds of the build finishing, long before Lighthouse runs. Tracking Bundle Size per Pull Request has the full setup.

Lab Versus Field

Lab tests answer "did this change make the page slower under fixed conditions?" Field data answers "are real readers having a good experience?" Both questions matter, and they disagree more often than teams expect.

The Chrome User Experience Report (CrUX) publishes 28-day rolling 75th-percentile values for LCP, INP and CLS for origins and popular URLs, and it is what Google's page experience signals use. Your own real-user monitoring gives the same metrics for every page with shorter lag. Comparing the two with lab numbers per template reveals where the lab profile is unrepresentative — for example, a documentation site whose readers mostly use fast desktops will see field LCP well below lab LCP, while a consumer blog read on older phones will see the reverse.

Use the comparison to calibrate: if field LCP p75 is 1.4 s while lab LCP is 2.1 s, your lab budget of 2.5 s has a lot of headroom and can tighten. The method is in Comparing Lab and Field Data with CrUX.

Budgets and Your Generator

The budget table above is generator-neutral, but each generator has a characteristic way of blowing through it, and knowing yours tells you which limit to set tightest.

Astro ships zero JavaScript by default, so its script budget is really a budget on islands. The regression to watch is a client:load directive added to a large component — a date picker, a carousel, a React design-system import — which can add 40–80 KB at once. Set the script-bytes error low (60 KB is realistic for a content site) and add a rule in review that any new client: directive needs a reason. Deferring Hydration with client:visible in Astro covers the cheaper directives.

Eleventy ships only what you add, which makes it the easiest to keep lean and the easiest to regress silently, because there is no framework convention for where scripts go. Budget request count as well as bytes: Eleventy sites tend to accumulate small separate script and stylesheet files from plugins and partials, each one a request and often render-blocking.

Hugo sites regress most often through images and CSS. Hugo Pipes makes resizing easy but does nothing unless templates call it, so an unprocessed 2 MB PNG in a new post sails through. Budget above-the-fold image bytes on the post template and assert the uses-responsive-images audit.

Next.js static export starts with the React runtime and router — typically 85–100 KB compressed before any page code — so a script budget below that is unachievable. Budget the per-route chunk instead, and watch for shared chunks growing as components are imported on more pages.

Docs frameworks carry their own baselines: measured on a 1,200-page corpus, Starlight pages shipped about 12 KB of JavaScript, VitePress about 58 KB and Docusaurus about 190 KB, as covered in Docs Frameworks: Docusaurus, Starlight and VitePress. Set budgets relative to your framework's floor, not to another framework's.

Handling a Failing Budget in Review

A budget is only as good as what happens when it fails. Three responses cover nearly every case, and writing them down in the repository's contributing guide saves a debate on every pull request.

Fix it in the same pull request. Most failures have an obvious cause visible in the Lighthouse report or the bundle-size comment: an image not run through the pipeline, a library imported whole, a font weight added. The author fixes it before merge. This should be the outcome for at least four failures in five.

Accept it with a raised budget. Sometimes the regression is the feature — a new interactive tool genuinely needs 30 KB of JavaScript. Raise the budget for that template in the same pull request, with the reason in the commit message, and have the budget owner approve it. The change is visible in history and can be revisited.

Defer it with a ticket. Rarely, a regression must ship for business reasons before it can be fixed. Mark the assertion warn for that template with a comment linking a ticket and a date, and have the budget owner restore error by that date. Without the date, deferrals become permanent.

What must never happen is the fourth response: disabling the check, or adding continue-on-error, to get a pull request through. A performance check that can be bypassed quietly stops being a check. Branch protection that makes the Lighthouse status required, with administrators included, removes the temptation.

When Lighthouse Is Not Enough

Lighthouse loads one page, cold, with one device profile. Some regressions only show up in multi-step journeys (a search dialog that blocks input, a slow client-side navigation) or on specific networks and locations. For those, scripted WebPageTest runs against the preview — logging in, opening search, navigating between pages — catch what a single cold load misses, and its filmstrips make a regression easy to explain in review. See Running WebPageTest Scripts Against Preview Deploys.

Reporting That People Read

Checks block merges; reports change habits. Two lightweight reports keep performance visible without a dashboard nobody opens.

The first is the pull request comment. Lighthouse CI's GitHub App or a small script posts a table of each template's LCP, TBT, CLS and script bytes against the base branch, with arrows for direction. Authors see the effect of their change without opening a report, and reviewers can ask about a 20 KB increase before it becomes a failure.

The second is a weekly trend note posted to the team channel: the median of each budgeted metric across the week's merged pull requests, the headroom left against each budget, and the field p75 values from the previous 28 days. It takes five minutes to automate from stored Lighthouse CI results and gives the budget owner the evidence to tighten a limit or to schedule clean-up work before a limit is hit. Teams that adopted the note in this study raised their median headroom on script bytes from 12% to 31% over a quarter, simply because slow creep became visible.

Store raw results somewhere queryable — a Lighthouse CI server, or JSON artefacts pushed to object storage — rather than relying on temporary public storage, which expires. Six months of history is what lets you tell a real trend from a noisy week.

Measured Impact

A documentation and blog site on Eleventy (1,400 pages, six templates) added byte budgets, Lighthouse CI on previews and bundle-size comments, then tracked every performance-related pull request for six months:

The one regression that escaped was a third-party chat widget loaded only for logged-in users, which Lighthouse never saw because it tested anonymous pages — a reminder to test the states your readers actually encounter.

Common Pitfalls

• Budgeting the score. The composite score changes weighting between Lighthouse versions and masks which metric moved. Budget metrics and bytes.
• Testing localhost. A local static server has no compression, CDN or cache headers. Test the preview URL.
• Single runs. One run is a sample, not a measurement. Use the median of three or more.
• Aspirational budgets. A budget that fails on day one gets disabled on day two. Start from current values and ratchet down.
• Testing only anonymous, cold pages. Consent banners, logged-in widgets and repeat visits each have their own performance profile.
• Nobody owns the budget. Assign an owner who reviews warnings weekly and tightens limits quarterly; otherwise warnings accumulate unread.

Key Takeaways

• Budget bytes as hard errors and timings as warnings until you know their spread; both beat budgeting the composite score.
• Run Lighthouse CI against preview deploys, one URL per template, median of three runs.
• Median-of-three kept LCP within 1.8–2.0 s on an unchanged page where single runs ranged from 1.6 to 2.4 s.
• Bundle-size comments on pull requests catch dependency regressions in seconds, before any browser runs.
• Field data from CrUX and RUM calibrates lab budgets; on one site, budgets cut production regressions from 11 to 1 in six months.

FAQ

What is a performance budget?

A set of limits a page must stay within, such as total JavaScript under 100 KB, LCP under 2.5 seconds in the lab, or no more than 20 requests. The budget is enforced in CI so a change that breaks it fails before it merges.

Should the budget be on scores or on metrics?

On metrics and bytes. The Lighthouse performance score is a weighted blend that shifts between versions and hides which metric moved. Budget LCP, TBT, CLS and resource sizes directly, and treat the score as a summary only.

Why do Lighthouse results vary between runs?

CPU contention on shared CI runners, network jitter, and timing-sensitive metrics all add noise. Run three to five times per URL, use the median, and budget byte sizes, which do not vary, alongside timing metrics, which do.

Do lab budgets guarantee good Core Web Vitals?

No. Lab tests use one device and network profile, while field data reflects real users. Lab budgets catch regressions early; field data from CrUX or your own RUM confirms whether real readers are affected.

Which pages should Lighthouse CI test?

One representative URL per template, plus the homepage. A static site with six templates needs six to eight URLs, not every page, because pages built from the same template share the same performance characteristics.

Related

• Up: Performance Optimization & Core Web Vitals for SSGs — the optimisations these budgets protect.
• Setting Up Lighthouse CI for a Static Site — the step-by-step wiring.
• Writing a Performance Budget That Fails Builds — turning the table above into config.
• Reducing Lighthouse Score Variance in CI — making timing budgets trustworthy.
• Tracking Bundle Size per Pull Request — the fastest, cheapest check.
• Comparing Lab and Field Data with CrUX — calibrating budgets against real readers.
• Running WebPageTest Scripts Against Preview Deploys — multi-step journeys Lighthouse misses.
• Measuring Build Time Regressions in CI — the same discipline applied to build speed.