Performance Budgets: Enforcing Speed in CI/CD

Performance Budgets: Setting Speed Limits for Your Website

A performance budget is a set of limits you place on your website's resources. It's like a speed limit for your code. You decide that your JavaScript bundle can't exceed 200KB, your images can't total more than 1MB, and your page must load in under 2 seconds. These limits help you keep your site fast as it grows.

Why You Need a Budget

Without a budget, performance tends to degrade over time. Someone adds a new library, then another, then a large image, then a third-party script. Each addition seems small on its own, but together they slow the site down. A budget catches these additions before they become a problem.

Budgets also create a shared understanding of what's acceptable. When a developer wants to add a new library, they can check if it fits within the budget. If it doesn't, they need to find a smaller alternative or optimize something else. This prevents the slow creep of bloat.

What to Budget For

Start with the most impactful resources: the total size of JavaScript, the total size of CSS, the total size of images, and the total number of requests. These directly affect how fast the page loads. You can also budget for specific metrics: Largest Contentful Paint under 2.5 seconds, First Input Delay under 100 milliseconds, Cumulative Layout Shift under 0.1.

More advanced budgets might include the number of third-party requests, the size of web fonts, or the amount of JavaScript executed on page load. The key is to measure what matters to your users and set limits accordingly.

Enforcing the Budget

A budget is only useful if it's enforced. The best way is to integrate it into your CI pipeline. When someone submits a pull request, the CI checks whether the changes would exceed the budget. If they would, the build fails. Tools like Lighthouse CI, bundlesize, and webpack's performance hints can automate this.

This creates a feedback loop: developers see the impact of their changes immediately and can make adjustments before merging. Over time, this builds a culture of performance awareness.

Setting Realistic Limits

Start by measuring your current performance. Where are you now? Then set a target that's ambitious but achievable. A common starting point is to aim for a 30% improvement. Once you reach that, set a new target. The goal is gradual, sustainable improvement, not a one-time optimization.

For a typical content site, a reasonable budget might be: 200KB of JavaScript (compressed), 100KB of CSS, 1MB of images, and under 20 requests. For a more complex web application, the numbers might be higher. The important thing is to set the budget, stick to it, and review it periodically.