Start Performance Budgeting

October 2, 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 can 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.

SpeedCurve perf budgets
SpeedCurve's performance budget alerts inform me when I've exceeded my JavaScript size budget.


Performance budgets are not just thresholds. 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.

metrics for performance budgets

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.

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.

JS Size budgets

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.

Milestone timing budgets - First Interactive

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:

SpeedCurve showing perf budgets for desktop/mobile for the Guardian

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.

Think about performance early on

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

Strategies for staying under budget

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.

SpeedCurve perf budgets and benchmaring

Tools for enforcing perf budgets

Many tools exist for enforcing performance budgets.

bundlesize is great for catching JavaScript size regressions in CI.

bundlesize uses bundlesize to set JavaScript bundle budgets which are checked on each PR commit. They have a main bundle budget of 170KB and a CSS budget of 20KB. Code-splitting enables them to remain within budgets.

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 perf budget

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

speedcurve budgets

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 alerts for when they regress.

If you're at the planning stages of deciding what your target budgets should be, is a visual aid with presets for different network speeds.

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. ❤️

Further reading