Case study: how one product team turned budgets into a repeatable workflow

A product team at a generic mid sized site needed a practical way to stop JavaScript weight and device work from creeping up. They wanted limits that are measurable in build artifacts, verifiable in CI, and visible in production. The approach below shows patterns that any team can adapt without requiring a specific tool or vendor.

Define measurable objectives

Start by naming what you will measure and why. With JavaScript this usually means tracking several related signals rather than a single number. Useful measurable objectives are JavaScript transfer size after compression, total parsing and compile time on the main thread, and the number of eager scripts loaded on first paint. These map directly to user experience because they affect time to interactive and responsiveness.

Pick a primary metric and secondary metrics

Choose one primary metric to gate on during early stages, and a small set of secondary metrics for monitoring. A common choice for the primary metric is compressed main bundle size measured in kilobytes because it is simple to check at build time. Complement that with lab checks of total main thread JavaScript work and production Real User Monitoring captures of parse and compile time so you do not miss device level regressions.

Set thresholds using evidence and risk tolerance

Thresholds should reflect product priorities and real user constraints. Derive them from a combination of representative field data and acceptable trade offs for performance. Treat any numbers you pick as starting points. For example, a team might treat 150 kilobytes gzipped for initial JS as a conservative example threshold and treat 250 milliseconds of total parse and compile time on a mid tier device as a warning level. Use lab tests and RUM to validate whether those thresholds produce the expected user experience before making them blocking rules.

Where to measure

Measure at three places simultaneously so you catch different classes of problems. First, at build time inspect artifact sizes and the list of emitted files. Second, in CI run synthetic tests with a deterministic environment using Lighthouse or a headless browser to capture main thread time and script evaluation. Third, in production collect RUM metrics that show actual parse and compile time and network transfer on real devices and networks.

Enforce budgets early in development

Make budgets visible and local to each change. Embed a lightweight size check in the local developer loop so authors see regressions before creating a review. Tools such as size limit or bundler plugins can run fast checks and report the resulting file sizes in human readable form. In pull requests include a generated artifact summary that shows current sizes compared with the allowed budget and an explanation of which entry points changed.

Gate in CI with progressive enforcement

1. Start with warnings to reduce friction. Configure CI to run the same checks as local builds and fail builds only after teams have adapted. Initially present failures as draft feedback rather than blocking merges so engineers can learn the new process.
2. When noise is low and teams accept the rules convert the most important budgets into blocking gates. Use a combination of quick build time checks for bundle size and slower lab tests for main thread work so CI remains practical.
3. Keep the gate logic transparent. Store budget values as code near the build configuration so changes require a PR and audit trail rather than being hidden in CI settings.

Make budgets part of pull request review

Display a short summary in the pull request that shows which budgets were touched, the delta for each budget, and a short explanation field where an author can justify increases or outline optimizations. This keeps reviewers focused on why a change affected the budget and what mitigation steps are planned.

Monitor production and alert on regressions

Lab checks do not replace real world monitoring. Collect RUM metrics that include JavaScript parse and compile duration, total transfer of JS per page load, and counts of third party scripts. Configure alerting when medians or p95 values cross thresholds. Use sampling and aggregation to avoid excessive noise and to ensure alerts point to real regressions rather than single user outliers.

Budget as code and configuration patterns

Keep budget definitions in the repository as a small file that is easy to read and change. Example fields include per route compressed size budgets, global main thread work limits, and exemptions for vendor bundles. Place that file with the build configuration so it is version controlled and reviewed like any other code change.

Ownership and governance

Assign a clear owner for the performance budget program. That person or small committee maintains the budget file, reviews exceptions, and coordinates periodic audits. Define a simple exception process: a temporary approved increase for a release when the trade off is justified, coupled with a remediation plan and deadline. This balances shipping needs with long term performance goals.

Handling third party scripts and vendor code

Third party scripts are a common source of budget pressure. Treat them as first class citizens in the budget calculation. Require vendors to document their compressed sizes and main thread impact. Where vendors are optional load them lazily or on user interaction. When a third party is essential prefer server side or edge alternatives that shift work away from the client.

Mitigation tactics when budgets are at risk

If a change pushes a budget over the limit choose fixes according to cost and impact. Low cost fixes include deferring non essential scripts, moving code to lazy loaded chunks, and removing duplication across bundles. Higher investment fixes include refactoring hot code paths to remove large dependencies or replacing a heavy library with a smaller focused implementation. Always measure the effect of a mitigation with the same checks used for enforcement.

Examples of checks and tools

There are multiple ways to implement checks. For quick local feedback use a size check tool that reads the bundle output and compares against the budget. For CI use an automated Lighthouse run or a headless Chromium script to capture total main thread JavaScript time. For production gather RUM metrics with an existing telemetry pipeline and compute aggregates for alerting. Keep the checks as simple as possible to reduce maintenance cost.

Decision criteria when adjusting budgets

Raise a budget only when evidence shows the change materially improves business goals and there is no cheaper way to deliver the value. When you increase a budget prefer doing so per route or per bundle instead of a global increase. That narrows the impact and keeps other parts of the product protected. Revisit budgets periodically after major platform changes such as a build tool migration or a new framework version.

Rollout checklist for teams

• Measure current state across representative pages and devices to set realistic starting thresholds.
• Place budget definitions in the repository under version control and document the rationale.
• Integrate quick local checks so developers receive immediate feedback before creating pull requests.
• Hook CI to run lab checks and annotate pull requests with the results.
• Begin with non blocking warnings and move to blocking gates when the process is stable.
• Collect RUM and configure alerts on medians and p95 for the chosen metrics.
• Maintain an exception process and a clear owner for the program.

Common pitfalls to avoid

Do not rely on a single artifact number without cross checking device level work. Avoid gating on overly strict thresholds that create constant failures and lead teams to disable the checks. Do not hide budget changes in CI settings; keeping them in the repository ensures visibility and review.

What success looks like

Over time success shows as a stable or decreasing trend in JavaScript transfer and main thread work, fewer performance regressions blocking releases, and faster feedback in the developer workflow. Importantly, success also means teams treat performance trade offs as part of product decision making rather than an afterthought.