A performance budget turns “make the site faster” into measurable release criteria. This guide shows how to set practical limits for JavaScript, CSS, images, fonts, requests, total page weight, and Core Web Vitals, then check those limits with browser DevTools, Lighthouse, and repeatable CI reports.
Overview
A website performance budget is a set of thresholds that a page or release should stay within. The budget may cover transfer size, resource counts, loading milestones, and user-focused outcomes. It is not a single number that applies to every website: a documentation page, ecommerce category page, marketing landing page, and authenticated web app have different requirements.
The useful starting point is to define a representative page and a representative user. For example, choose a mobile product page on a typical network, rather than testing only a lightweight homepage on a fast development machine. Record the page’s initial JavaScript, CSS, image, font, and HTML sizes, along with request count and Core Web Vitals. That baseline gives the team evidence for setting limits instead of choosing arbitrary targets.
A budget should support decisions before release. If a new library adds 90 KB to the initial JavaScript payload, the team should be able to see whether that change exceeds the agreed limit, improves an important user flow, or requires a documented exception. This makes performance part of technical SEO and content workflow rather than a final polish step.
For related debugging work, see the CSS Flexbox and Grid Debugging Guide. Layout instability, oversized media, and late-loading components often need to be investigated together.
How to estimate
1. Choose the page, device, and test condition
Start with one page type that matters to search visitors or business goals. Define the URL, viewport, browser, connection profile, cache state, and whether the test is logged in. Use the same conditions for comparisons. A cold-cache run helps reveal the cost of first visits; a warm-cache run shows how repeat visitors experience the page. Keep both if returning users are important.
2. Measure a baseline
Use browser DevTools to inspect the Network panel and group resources by type. Record transferred bytes, resource size, request count, and timing. Use the Performance panel to identify long tasks, layout shifts, and blocking work. Run Lighthouse several times rather than relying on one result, because lab measurements vary with system and network conditions.
Where available, compare lab results with real-user data. Lab tools are useful for controlled release checks; field data reflects actual devices, networks, and interactions. Treat a single Lighthouse score as a diagnostic signal, not as the entire definition of performance.
3. Set budgets from the baseline
Decide which values must not grow and which values should improve. A simple first budget can be based on the current page with a small tolerance for normal variation. A more ambitious budget can be based on a desired user experience. Separate hard limits, such as maximum initial JavaScript, from warning thresholds, such as a preferred request count.
For Core Web Vitals, commonly used “good” targets are LCP at or below 2.5 seconds, INP at or below 200 milliseconds, and CLS at or below 0.1. Verify the current definitions and evaluation guidance when maintaining this article or a release policy. A page can meet byte budgets and still perform poorly if JavaScript blocks interaction or content shifts during loading.
4. Automate the comparison
Run a repeatable Lighthouse or equivalent performance check for important routes in CI or a scheduled job. Store the URL, commit, test configuration, metric values, and pass or fail result. Use thresholds that allow for small measurement noise, and investigate repeated failures rather than rejecting a release because of one unusual run. A report should identify the resource or metric that changed, not merely display a score.
Inputs and assumptions
Use this worksheet for each page type. Fill in a baseline, a target, and an allowed exception.
| Budget area | What to measure | Planning question |
|---|---|---|
| JavaScript | Initial transfer size, parsed size, execution time, long tasks | Which code is required before the first interaction? |
| CSS | Transferred bytes, blocking stylesheets, unused rules | Can critical styles be smaller or loaded earlier? |
| Images | Transferred bytes, dimensions, format, loading behavior | Are images correctly sized for their rendered space? |
| Fonts | Font files, weights, formats, blocking time | Are all weights needed on the first view? |
| Requests | Total requests and requests before meaningful content | Which third-party or duplicate requests can wait? |
| Page weight | Total transferred bytes and resource breakdown | What is the maximum acceptable first-visit cost? |
| Experience | LCP, INP, CLS, and key interaction timings | Can users see and use the page without waiting? |
Document assumptions beside every number. “JavaScript under 250 KB” is incomplete unless it specifies whether the value means compressed transfer size, uncompressed resource size, or all scripts loaded during the initial view. Likewise, “fewer than 60 requests” should state whether it includes analytics, third-party embeds, preloads, and requests made after the page becomes interactive.
For image budgets, measure the delivered resource, not only the source file stored in a content system. Use responsive images, modern compression where supported, explicit width and height attributes, and lazy loading for below-the-fold media when appropriate. Do not lazy-load the main content image simply to reduce a count if doing so delays the page’s primary content.
For JavaScript, distinguish code downloaded from code executed. A small bundle can still create a slow page if it performs expensive parsing, hydration, or event-handler work. Review the dependency graph and use coverage and flame charts to find code that is not needed for the initial route.
Worked examples
Example A: a content-led landing page
Suppose the baseline includes 210 KB of compressed initial JavaScript, 42 KB of CSS, 520 KB of images, six font files, and 78 requests. The page also shows an LCP of 3.1 seconds in the chosen mobile lab condition. The team might set an initial budget of 220 KB for JavaScript, 50 KB for CSS, 600 KB for above-the-fold and near-fold images, four font files, and 80 requests. The LCP target should be brought toward the selected good threshold, not treated as guaranteed by the byte limits alone.
After a redesign adds a video embed and two analytics vendors, the page reaches 95 requests and 760 KB of images. The release review should identify the cost of each addition, defer nonessential embeds, and test whether the video can load after interaction. If the additions are necessary, record the reason, owner, mitigation, and date for review rather than silently raising every budget.
Example B: a JavaScript-heavy application route
An authenticated dashboard may legitimately require more JavaScript than a public article. Its budget should focus on the first useful interaction: navigation, filtering, or opening a record. Measure the time from input to response, long tasks during startup, and the amount of code loaded for the first route. Split large features, defer secondary panels, and avoid treating a higher total application size as an excuse for slow interaction.
For API-driven pages, inspect request waterfalls as well as bundles. A compact frontend can still wait on serial API calls. The REST API Testing Workflow can help isolate request timing, payload size, and response behavior when network activity is the limiting factor.
Budget worksheet
Copy this compact format into a project document:
- Page and URL:
- Primary user and device:
- Connection and cache condition:
- Initial JavaScript: baseline / target / actual:
- CSS: baseline / target / actual:
- Images: baseline / target / actual:
- Fonts: baseline / target / actual:
- Total requests: baseline / target / actual:
- Total transfer: baseline / target / actual:
- LCP / INP / CLS: baseline / target / actual:
- Exceptions, owner, mitigation, and review date:
When to recalculate
Revisit the budget whenever the page architecture or user journey changes. Important triggers include a redesign, a new frontend framework or dependency, a third-party script, a new font family, a video or interactive embed, a major image-library change, a CMS migration, or a new personalization layer. Recalculate after changing hosting, caching, compression, CDN configuration, or API behavior as well.
Review the measurement method at least quarterly for important sites and whenever browser tooling or Core Web Vitals guidance changes. Confirm that Lighthouse settings, browser versions, device profiles, and field-data definitions still match the release policy. A budget that cannot be reproduced is difficult to enforce.
Use this release checklist:
- Test the same representative URLs under the documented conditions.
- Compare resource sizes, request counts, and timing with the previous baseline.
- Check LCP, INP, CLS, and the page’s primary interaction.
- Inspect new third-party requests and changes in JavaScript execution.
- Review image dimensions, font loading, caching, and compression.
- Run the automated report and save the result with the commit or release.
- For every exception, document its benefit, cost, mitigation, owner, and review date.
Keep the budget visible to developers, SEO specialists, content teams, and product owners. When a landing page or template is approved, its performance limits should be recorded alongside other technical SEO checks. The Technical SEO Content QA Checklist provides a useful place to connect page performance with broader publishing checks.