Start Performance Budgeting

7 min readOct 8, 2018

If you’re building a web experience and want to stay fast, a performance budget can be critical. For success, embrace performance budgets and learn to live within them. Network & CPU limits on mobile can require asking hard questions like, “what is really important to my users?”

When we talk to Fortune 500 companies that put in the work to improve performance, perf metrics will often rapidly regress once they return to feature development. Performance budgets help teams prioritize features, optimizations and facilitate discussions on what is really important to users.

“Having a pre-defined ‘budget’ is a clear, tangible way to frame decisions about what can and can’t be included, and at a suitably early stage in the project” — Mark Perkins

What’s a performance budget?

A performance budget is a limit for pages which the team is not allowed to exceed. It could be a max JavaScript bundle size, total image weight, a specific load time (e.g Time-to-Interactive in under 5s on 3G/4G) or threshold on any number of other metrics.

Performance budgets are not just thresholds however. Much like a financial budget, they’re something consciously spent. View them as a currency to spend and trade on user-experience. In an environment where the cost of JavaScript is still high on mobile devices, budgets are one of the few tools that can help guide us to success.

Metrics for perf budgets

Metrics for perf budgets can include milestone timings, quantity-based metrics or rule-based metrics.

Milestone timings: timings based on the user-experience loading a page (e.g Time-to-Interactive, First Contentful Paint). You’ll often want to pair several milestone timings to accurately represent the complete story during page load. Some teams also maintain custom metrics, like “Time to first tweet” for Twitter.

Quantity-based metrics: based on raw values (e.g. weight of JavaScript (KB/MB), number of HTTP requests). These are focused on the browser experience.

Rule-based metrics: scores generated by tools such as Lighthouse or WebPageTest. Often, a single number or series to grade your site.

Teams who incorporate perf budgets will often have CI warn or error a build if a PR regresses performance. Lighthouse CI now supports failing a Lighthouse score when a category (such as performance) has fallen under a certain value:

An example of a “rule” based performance budget in action. Using Lighthouse CI, we can enforce budgets on a performance score. PRs can be failed if their perf score falls below a certain value.

Examples of budgets

Our product page must ship less than 170KB of JavaScript on mobile
Our search page must include less than 2MB of images on desktop
Our home page must load and get interactive in < 5s on Slow 3G/Moto G4
Our blog must score > 80 on Lighthouse performance audits

Below is a quantity metric — JS Size for The Guardian’s desktop site on SpeedCurve. It highlights in yellow when under budget and red when over budget.

We can also visualize a milestone metric. Below is First Interactive (now First CPU Idle) — marking the point when the browser’s main thread is not blocked for more than 50ms by any single task so user input can be responded to quickly.

Budgets can vary by a number of factors including target device class. Comparing the Guardian’s mobile and desktop experiences we can see their total weights differ heavily:

This may suggest having budgets for different device classes are worth considering. e.g. < 170KB JS (min/gzip) for mobile and < 1.5MB for desktop where users may have faster CPUs and network connections.

Quantifying the impact of new features

“Deciding a page can’t exceed 500kB when a mock-up containing three carousels and a full-screen high-resolution background image has already been approved isn’t going to do you much good” — Tim Kadlec

Often, non-engineering stakeholders are unaware of the performance consequences of their decisions on features or design. This is not their fault. We need to make it easier for PMs, designers and stakeholders to understand the user-experience impact of their choices.

Stakeholders may need help understanding that another JavaScript carousel or plethora of images can heavily impact the performance of a site. Perf budgets can help strategically change mindset towards questioning the value of each thing we add.

Even better is if we can make performance part of project goals from the start. This shifts the mentality of perf budgets only being a factor thought of during development to one where it’s key throughout the project lifecycle.

Making trade-offs for user-experience

As with any financial budget, there may be times when your perf budget will be low. This can require you to make cuts or trade-offs in order to maintain a consistently fast user-experience. What features are really important to your users? Which ones excite or retain them the most?. This is a difficult conversation and is not always clear cut.

This conversation can result in dropping one feature to allow for another. ‘Dropping’ could mean removing it from the critical-path — the feature could still be loaded on-demand at a later point when the user needs it.

In such situations, you can make a call on a page-by-page basis while consulting the performance budget as the source of truth so you can continue to reach your goals.

Operationalizing budgets

Performance budgets are aided by having internal processes for operationalizing a performance culture within a business.

Organizational performance budgets ensure that a budget is owned by everyone rather than just being defined by one group. Perf budgets can’t be something only engineering teams care about.

“Web performance budgets should be a collaborative effort about the right factors to create an equation to help the business make the right decisions and generate necessary insights to move its product forward. This is far more fruitful than a potentially antagonizing conversation about sticking to a fixed web performance threshold.” — Tobias Baldauf

When budgets have been set and the entire organization is aware early on what the budget parameters are, you’re able to say performance isn’t just an engineering issue, but a critical piece of the whole package as a site is constructed.

It provides a guideline for design and engineering when considering performance and should be checked with each decision that could impact performance.

Monitoring services like SpeedCurve also enable you to benchmark your site against competitors, allowing you to easily visualize how they perform on your budgets. This can be a powerful aid when speaking to stakeholders about why staying “under-budget” is important.

Tools for enforcing performance budgets

Many tools exist for enforcing performance budgets.

bundlesize is excellent for catching JavaScript size regressions in CI:

Tinder.com uses bundlesize to set JavaScript bundle budgets which are checked on each PR commit. Their React app has a main bundle budget of 170KB and a CSS budget of 20KB. Code-splitting enables them to remain within budgets. Sites like Trivago, Zendesk & OpenTable also use it.

Other teams use Webpack’s built-in support for perf budgets. You can configure performance.hints to warn or fail a build when budgets are crossed. Webpack supports a max asset size or entry point size for JavaScript bundles.

SpeedCurve support setting budgets for a wide range of metrics, resource sizes and Lighthouse audit categories.

A demo tracking the Lighthouse performance score of blog.google with a budget of 80/100. Red shows where the budget has been exceeded.

Zillow use SpeedCurve to set budgets for their quantity (e.g. image size) and milestone timing metrics in mobile search. Other performance monitoring services like Calibre also support setting budgets and alerting.

If you’re at the planning stages of deciding what your target budgets should be, https://performancebudget.io is a visual aid with presets for different network speeds.

and of course, as mentioned earlier, Lighthouse CI is a great option for teams that want to enforce rule-based performance budgeting for PRs.

Closing thoughts

Performance budgets usher a culture of accountability that enable stakeholders to weigh the impact to user-centric metrics of each change to a site. Talk to your organization and see if you can get by in to adopt performance budgets for your projects. If it’s worth getting fast, it’s worth staying fast. ❤️