The performance budget playbook: bytes that matter

The performance budget playbook: bytes that matter.

Every kilobyte of JavaScript costs your users. It costs them on slow 4G. It costs them on a mid-range Android phone. It costs them on a laptop with eight tabs open.

A 240 KB gz cap on your own JS keeps Largest Contentful Paint under 2 seconds on a Moto G4. That is the target. Here is how to hit it.

The per-route caps.

Home, the services hub and each service page share a 240 KB gz JS cap. The blog hub and each post share the same cap. The tools hub shares it too. Contact gets 245 KB. Its layout is richer and it loads third-party code. Code from other sites is capped at 50 KB gz on all routes.

How to enforce caps in CI.

The check runs on all pull requests. If a route ships over its cap with no written reason, the build fails.

The reason must name the route. It must say what the extra bytes buy. It must carry a date to come back to.

The tool writes a JSON report with byte counts for each route. The CI step reads that report. It blocks the merge if any route is over with no override.

When a cap really must change, update it in the route map and say why. Our 30-day marketing website guide covers where that lands in the build.

Five ways to keep bytes in check.

Send headings, body copy, FAQ and schema from the server. The javascript crawling guide shows how to check what your server actually returns. Search engines and AI bots read them with no JavaScript. Your users see the words before the code loads.

One LCP image per page. Preload it at high priority. Never lazy-load it. Use AVIF first, WebP as the backup. Set width and height so the browser keeps that space.

No inline video. Embed from YouTube instead. Add a written summary. An inline player ships 500 KB of JS before the user presses play.

Drop dead code. Most icon libraries ship all icons, even ones you never use. Use the auto-import setting that cuts what you skip.

Lazy-load all of it below the fold. Modals, accordions and sliders load only when the user reaches them.

What to measure, not just count.

Byte counts are the output. The number that matters is Largest Contentful Paint (LCP). Target under 2.5 seconds. The next one is Cumulative Layout Shift (CLS). Target under 0.1. The third is Interaction to Next Paint (INP). Target under 200ms.

LCP comes from the LCP image and how you render on the server. CLS mostly comes from images with no size set, or web fonts that flash or shift. High INP mostly means JS is blocking the main thread when the user tries to click.

Run these in Lighthouse on a slow phone profile, or paste your URL into our Core Web Vitals tester. A cap that passes on a fast laptop means nothing if the page fails on a mid-range Android phone.

When to review a cap.

Open a review when a route stays over its cap. The review has two possible outcomes. Either the cap was wrong for the route, or the build was wrong.

In both cases, write down the call. Name one person who owns the review. Set a date for the next one. Run these reviews each quarter, even when nothing is over.

The 30-day marketing website guide covers how we set budgets in the week 3 build. The same CI check applies to all the work we take on.