Web Performance Budgets: Setting, Enforcing, and Automating Performance Limits

What Is a Performance Budget?

A performance budget is a set of quantifiable limits on metrics that affect user experience. These limits act as guardrails, preventing performance regressions from reaching production. Unlike aspirational performance goals, budgets are enforced — builds that exceed them fail, pull requests get flagged, and teams are alerted before degradation ships.

Performance budgets transform performance from a reactive concern into a proactive engineering discipline. They make trade-offs explicit: adding a new feature or dependency requires fitting within the budget or making room by optimizing elsewhere.

Choosing the Right Metrics

Effective performance budgets combine multiple metric types to cover different aspects of user experience:

Milestone Metrics

• Largest Contentful Paint (LCP) — the most important loading metric. Budget: under 2.5 seconds on 4G connection.
• Time to Interactive (TTI) — when the page becomes reliably interactive. Budget: under 3.5 seconds.
• First Contentful Paint (FCP) — first visual feedback. Budget: under 1.8 seconds.

Quantity-Based Metrics

• Total JavaScript size — compressed transfer size. Budget: under 300KB for most sites.
• Total page weight — all resources combined. Budget: under 1.5MB on initial load.
• HTTP request count — total number of requests. Budget: under 50 for initial page load.
• Third-party script size — external dependencies. Budget: under 100KB compressed.

Rule-Based Metrics

• Lighthouse performance score — composite score. Budget: above 90.
• Core Web Vitals assessment — all three metrics passing. Budget: all green.

Setting Budget Thresholds

Setting the right thresholds requires balancing ambition with practicality. Here is a proven methodology:

1. Baseline your current performance. Run Lighthouse and WebPageTest on your key pages. Record all metrics across desktop and mobile profiles.
2. Benchmark against competitors. Test your top 3-5 competitors with the same tools. Your budget should aim to be at least 20% faster than the fastest competitor on critical metrics.
3. Account for user conditions. Test on mid-tier devices (Moto G Power) with throttled 4G connections. This represents the experience of your median mobile user.
4. Set initial budgets at current baseline. Prevent things from getting worse before trying to make them better. Then tighten gradually — reduce budgets by 10-15% per quarter.
5. Define budgets per page template. Homepage, product pages, and checkout flows have different performance profiles and should have separate budgets.

Performance Budget Configuration

Here is an example budget configuration file that can be used with Lighthouse CI or similar tools:

{
  "budgets": [
    {
      "path": "/*",
      "timings": [
        { "metric": "largest-contentful-paint", "budget": 2500 },
        { "metric": "first-contentful-paint", "budget": 1800 },
        { "metric": "cumulative-layout-shift", "budget": 0.1 },
        { "metric": "interactive", "budget": 3500 }
      ],
      "resourceSizes": [
        { "resourceType": "script", "budget": 300 },
        { "resourceType": "total", "budget": 1500 },
        { "resourceType": "third-party", "budget": 100 }
      ],
      "resourceCounts": [
        { "resourceType": "total", "budget": 50 },
        { "resourceType": "script", "budget": 15 }
      ]
    }
  ]
}

CI/CD Integration

Automated enforcement in the CI/CD pipeline is where performance budgets deliver the most value. Without automation, budgets are just suggestions.

Lighthouse CI

Lighthouse CI runs audits against every pull request and fails builds that exceed budgets:

# .lighthouserc.json
{
  "ci": {
    "collect": {
      "url": ["http://localhost:3000/", "http://localhost:3000/product"],
      "numberOfRuns": 3
    },
    "assert": {
      "assertions": {
        "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
        "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }],
        "resource-summary:script:size": ["error", { "maxNumericValue": 307200 }]
      }
    },
    "upload": {
      "target": "temporary-public-storage"
    }
  }
}

Bundlesize and Size-Limit

For JavaScript bundle budgets specifically, tools like size-limit provide fast, accurate checks:

# package.json
{
  "size-limit": [
    { "path": "dist/app.js", "limit": "150 KB" },
    { "path": "dist/vendor.js", "limit": "120 KB" },
    { "path": "dist/**/*.css", "limit": "50 KB" }
  ]
}

Enforcement Tools Comparison

Tool	Metric Types	CI Integration	PR Comments
Lighthouse CI	Timing, size, score	GitHub Actions, GitLab CI	Yes
size-limit	Bundle size, load time	Any CI	Yes (with action)
bundlewatch	Bundle size	Any CI	Yes
SpeedCurve	All (RUM + synthetic)	API документацию-based	Slack/webhook

Maintaining Budgets Over Time

• Review budgets quarterly and tighten them as optimizations are made — never let budgets drift upward.
• When a new feature legitimately needs more budget, require the team to offset it by optimizing elsewhere.
• Track budget trends in dashboards to visualize performance trajectory over months.
• Celebrate teams that reduce their page weight or improve LCP — make performance a visible engineering value.
• Include performance budget status in sprint reviews and release checklists.

Conclusion

Performance budgets are the most effective mechanism for preventing performance regressions at scale. By choosing the right metrics, setting realistic thresholds, and enforcing them through CI/CD automation, teams can maintain fast user experiences even as applications grow in complexity. Start with a few critical metrics, automate enforcement, and expand coverage over time.