Performance budgets that work: practical limits for fast web apps

Why performance needs budgets, not just good intentions

A performance budget is a set of limits you agree on before you build. It can be a time limit (how fast the page feels), a size limit (how much code you ship), or a simple cap (requests, images, third-party scripts). If you go over the limit, it’s treated like a broken requirement, not a “nice to fix later” task.

Speed usually gets worse because shipping is additive. Each new widget adds JavaScript, CSS, fonts, images, API calls, and more work for the browser. Even small changes stack up until the app feels heavy, especially on mid-range phones and slower networks where most real users are.

Opinions don’t protect you here. One person says “it feels fine on my laptop,” another says “it’s slow,” and the team debates. A budget ends the debate by turning performance into a product constraint you can measure and enforce.

This is where Addy Osmani’s thinking fits: treat performance like design constraints and security rules. You don’t “try” to stay secure or “hope” the layout looks good. You set standards, you check them continuously, and you block changes that break them.

Budgets solve several practical problems at once. They make tradeoffs explicit (adding a feature means paying for it somewhere else), they catch regressions early (when fixes are cheaper), and they give everyone the same definition of “fast enough.” They also reduce the late panic that tends to show up right before a launch.

Here’s the kind of scenario budgets are built for: you add a rich charting library for one dashboard view. It ships to everyone, grows the main bundle, and pushes the first meaningful screen later. Without a budget, this slips through because the feature “works.” With a budget, the team has to choose: lazy-load the chart, replace the library, or simplify the view.

This matters even more when teams can generate and iterate on apps quickly, including with chat-driven build workflows like Koder.ai. Speed is great, but it also makes it easy to ship extra dependencies and UI flourishes without noticing. Budgets keep fast iteration from turning into slow products.

Start with a simple target: page, device, and network

Performance work fails when you measure everything and own nothing. Pick one page flow that matters to real users, and treat it as the anchor for your budgets.

A good starting point is a primary journey where speed affects conversion or daily work, like “home to signup,” “dashboard first load after login,” or “checkout and payment confirmation.” Choose something representative and frequent, not an edge case.

Choose a target that matches your users

Your app doesn’t run on your laptop. A budget that looks fine on a fast machine can feel slow on a mid-range phone.

Decide on one target device class and one network profile to start. Keep it simple and write it down as a sentence everyone can repeat.

For example: a mid-range Android phone from the last 2 to 3 years, on 4G while moving around (not office Wi‑Fi), measuring a cold load and then one key navigation, in the same region where most users are.

This isn’t about picking the worst case. It’s about choosing a common case you can actually optimize for.

Lock one baseline test setup

Numbers only matter if they’re comparable. If one run is “Chrome with extensions on a MacBook” and the next is “throttled mobile,” your trend line is noise.

Pick one baseline environment and stick to it for budget checks: same browser version, same throttling settings, same test path, and the same cache state (cold or warm). If you use real devices, use the same device model.

Now define what “fast enough” means in terms of behavior, not perfect demos. For example: “users can start reading content quickly” or “the dashboard feels responsive after login.” Translate that into one or two metrics for this journey, then set budgets around them.

Budget types: timing, size, requests, and runtime

Budgets work best when they cover both what users feel and what teams can control. A good set mixes experience metrics (the “did it feel fast?” part) with resource and CPU limits (the “why did it get slow?” part).

Timing budgets (user experience)

These track how the page behaves for real people. The most useful ones map directly to Core Web Vitals:

• LCP (Largest Contentful Paint): how quickly the main content appears.
• INP (Interaction to Next Paint): how responsive the page is when someone taps, clicks, or types.
• CLS (Cumulative Layout Shift): how much the layout jumps around.

Timing budgets are your north star because they match user frustration. But they don’t always tell you what to fix, so you also need the budget types below.

Size, request, and runtime budgets (what causes slowness)

These are easier to enforce in builds and reviews because they’re concrete.

Weight budgets cap things like total JavaScript, total CSS, image weight, and font weight. Request budgets cap total request count and third-party scripts, reducing network overhead and “surprise” work from tags, widgets, and trackers. Runtime budgets limit long tasks, main-thread time, and hydration time (especially for React), which often explains why a page “feels” slow on mid-range phones.

A practical React example: bundle size might look fine, but a new carousel adds heavy client-side rendering. The page loads, yet tapping filters feels sticky because hydration blocks the main thread. A runtime budget like “no long tasks over X ms during startup” or “hydration completes within Y seconds on a mid-tier device” can catch this even when weight budgets don’t.

The strongest approach treats these as one system: experience budgets define success, and size, request, and runtime budgets keep releases honest and make “what changed?” easy to answer.

Concrete starter budgets you can actually enforce

If you set too many limits, people stop paying attention. Pick 3 to 5 budgets that match what users feel most, and that you can measure on every pull request or release.

A practical starter set (tune the numbers later):

• LCP: warn at 2.5s, fail at 3.0s (mobile, cold load).
• INP: warn at 200ms, fail at 300ms (common interactions like opening a menu or submitting a form).
• CLS: warn at 0.10, fail at 0.15.
• JavaScript bundle size (initial route): warn at 170KB gzip, fail at 220KB gzip (app code only).
• Images (initial view): warn at 800KB, fail at 1.2MB (total transferred bytes for images loaded on the first screen).

Two thresholds keep things sane. “Warn” tells you you’re drifting. “Fail” blocks a release or requires explicit approval. That makes the limit real without creating constant fire drills.

Write the budget down in one shared place so nobody debates it during a busy release. Keep it short and specific: which pages or flows are covered, where measurements run (local audit, CI, staged build), which device and network profile you use, and exactly how metrics are defined (field vs lab, gzip vs raw, route-level vs whole app).

Step by step: set budgets from your current app

Start with a baseline you can repeat. Pick one or two key pages and test them on the same device profile and network each time. Run the test at least three times and record the median so one weird run doesn’t set your direction.

Use a simple baseline sheet that includes both a user metric and a build metric. For example: LCP and INP for the page, plus total JavaScript size and total image bytes for the build. This makes budgets feel real because you can see what the app shipped, not just what a lab run guessed.

Set budgets slightly better than today, not fantasy numbers. A solid rule is 5 to 10 percent improvement from your current median on each metric you care about. If your LCP is 3.2s on your baseline setup, don’t jump straight to 2.0s. Start with 3.0s, then tighten after you prove you can hold it.

Add a quick check to every release before users see it. Keep it fast enough that people don’t skip it. A simple version is: run a single-page audit on the agreed page, fail the build if JavaScript or images exceed the budget, store results per commit so you can see when it changed, and always test the same URL pattern (no random data).

Review breaches weekly, not only when someone complains. Treat a breach like a bug: identify the change that caused it, decide what to fix now, and what to schedule. Tighten slowly, only after you’ve held the line for a few releases.

When product scope changes, update budgets deliberately. If you add a new analytics tool or a heavy feature, write down what grew (size, requests, runtime), what you’ll do to pay it back later, and when the budget should return.

Quick audits: a fast way to see what changed

A budget only helps if you can check it quickly. The goal of a 10-minute audit isn’t to prove a perfect number. It’s to spot what changed since the last good build and decide what to fix first.

A 10-minute audit flow

Start with one page that represents real usage. Then run the same quick checks every time:

• Identify the LCP element (hero image, heading block, product gallery). If the LCP element changed, your results will jump.
• Check JavaScript weight and the largest chunks. Look for a new dependency, a duplicated library, or a big feature shipped to everyone.
• Scan above-the-fold images for common mistakes (uncompressed assets, wrong dimensions, missing responsive sources).
• Review third-party tags (analytics, chat, A/B tests). One new tag can add long tasks and block the main thread.
• Look at network and CPU together: is it slow because bytes increased, or because the page is doing too much work?

How to spot the biggest issues fast

Two views usually give you answers in minutes: the network waterfall and the main-thread timeline.

In the waterfall, look for one request that dominates the critical path: a giant script, a blocking font, or an image that starts late. If the LCP resource isn’t requested early, the page can’t hit an LCP budget no matter how fast the server is.

In the timeline, look for long tasks (50 ms or more). A cluster of long tasks around startup often means too much JavaScript on first load. One massive chunk is usually a routing issue or a shared bundle that grew over time.

Notes that make the next test comparable

Quick audits fail when each run is different. Capture a few basics so changes are clear: page URL and build/version, test device and network profile, LCP element description, the key numbers you track (for example LCP, total JS bytes, request count), and a short note on the biggest offender.

Desktop testing is fine for quick feedback and PR checks. Use a real device when you’re close to the budget, when the page feels janky, or when your users skew mobile. Mobile CPUs make long tasks obvious, and that’s where many “looks fine on my laptop” releases fall apart.

What to fix first: simple rules that save time

When a budget fails, the worst move is to “optimize everything.” Use a repeatable triage order so each fix has a clear payoff.

A practical triage order

Start with what users notice most, then work down toward finer tuning:

• Make the main above-the-fold element fast. Find what paints as the largest content and fix that asset or rendering path first. Resize and compress images, use the right format, and avoid late-loading fonts that block the first view.
• Cut JavaScript before polishing CSS. If the page ships too much JS, everything else suffers: slower parsing, longer main-thread work, delayed rendering. Remove unused code, split heavy routes, and prefer server-rendered or static content for simple UI.
• Tame third-party scripts early. Chat widgets, analytics, tag managers, and A/B tools can add big downloads and long tasks. If something isn’t needed at first view, delay it. If it’s low value, remove it.
• Stop layout shifts by design. Reserve space for images, ads, and embeds. Set width/height, use stable placeholders, and avoid injecting UI above existing content after load.
• If interaction is laggy, kill long tasks. When INP is poor, look for heavy client-side work: large renders, expensive state updates, and big JSON processing. Break work into smaller chunks, reduce rerenders, and move non-UI work off the critical path.

A quick example

A team ships a new dashboard and suddenly misses the LCP budget. Instead of tweaking cache headers first, they find the LCP element is a full-width chart image. They resize it, serve a lighter format, and load only what matters early. Next, they notice a large charting library loads on every route. They load it only on the analytics page and delay a third-party support widget until after the first interaction. Within a day, the dashboard is back within budget, and the next release has clear “what changed” answers.

Common mistakes teams make with performance budgets

The biggest failure mode is treating budgets like a one-time document. Budgets only work when they’re easy to check, hard to ignore, and tied to how you ship.

The mistakes that make budgets fail

Most teams get stuck in a few traps:

• Setting too many budgets on day one, or setting them so strict that every build fails.
• Measuring with different settings each time (device, throttling, cache state, test page).
• Chasing lab scores while missing real user pain.
• Letting one big dependency slip in quietly.
• Treating performance like a project you finish instead of a release rule.

A common pattern is a “small” feature that pulls in a new library. The bundle grows, LCP slows by a second on slower networks, and nobody notices until support tickets arrive. Budgets exist to make that change visible at review time.

How to avoid them

Start simple and keep checks consistent. Pick 2 to 4 budgets that map to user experience and tighten them gradually. Lock your test setup and write it down. Track at least one real-user signal if you can, and use lab tests to explain the “why,” not to win arguments. When a dependency adds meaningful weight, require a short note: what it costs, what it replaces, and why it’s worth it. Most importantly, put the budget check on the normal release path.

If budgets feel like constant friction, they’re usually unrealistic for today, or they aren’t tied to real decisions. Fix those two things first.

Example: turning a slowing web app into a budgeted release process

A small team shipped a React analytics dashboard in a week. It felt fast at first, but every Friday release made it a bit heavier. After a month, users started saying the first screen “hangs” and filters feel laggy.

They stopped arguing about “fast enough” and wrote down budgets tied to what users notice:

• LCP: 2.5s on a mid-range phone on 4G
• INP: under 200ms for common actions (open menu, apply filter)
• JavaScript: 250KB gzip for the initial route, with a clear cap per new feature
• Images: no uncompressed hero images, and a max pixel size per component

The first failure showed up in two places. The initial JavaScript bundle crept up as charts, date libraries, and a UI kit were added. At the same time, the dashboard header image was swapped for a bigger file “just for now,” pushing LCP over the limit. INP got worse because each filter change triggered heavy rerenders and expensive calculations on the main thread.

They fixed it in an order that produced quick wins and prevented repeat regressions:

1. Get LCP back under the line by resizing and compressing images, setting explicit image dimensions, and avoiding blocking font loads.

2. Cut initial JS by removing unused libraries, splitting non-critical routes, and lazy-loading charts.

3. Improve INP by memoizing expensive components, debouncing typing filters, and moving heavy work off the hot path.

4. Add a budget check to every release so if a metric breaks, the release waits.

After two releases, LCP dropped from 3.4s to 2.3s, and INP improved from around 350ms to under 180ms on the same test device.

Checklist and next steps (including a light Koder.ai workflow)

A budget only helps if people can follow it the same way every time. Keep it small, write it down, and make it part of shipping.

Pick a handful of metrics that fit your app, set “warn vs fail” thresholds, and document exactly how you test (device, browser, network, page/flow). Save a baseline report from the current best release and label it clearly. Decide what counts as a valid exception and what doesn’t.

Before each release, run the same audit and compare it to the baseline. If something regresses, log it where you track bugs and treat it like a broken checkout step, not a “later” task. If you ship with an exception, record an owner and an expiry date (often 1 to 2 sprints). If the exception keeps getting renewed, the budget needs a real discussion.

Move budgets earlier into planning and estimates: “This screen adds a chart library, so we need to remove something else or lazy-load it.” If you’re building with Koder.ai (koder.ai), you can also write these constraints up front in Planning Mode, then iterate in smaller slices and use snapshots and rollback when a change pushes the app over a cap. The point isn’t the tool, it’s the habit: every new feature has to pay for its weight, or it doesn’t ship.