Bundle Size Budget Calculator

A performance budget sets maximum thresholds for page weight metrics — JS bundle size, CSS size, total page weight, number of requests. Budgets make performance a first-class constraint in development. Google recommends keeping total page weight under 500KB for fast-loading pages, with JavaScript under 200KB compressed. Exceeding budgets should trigger a review before merging code. Tools like Lighthouse, bundlesize, and size-limit can automate budget enforcement in CI.

The commonly cited guideline is 200KB compressed (gzip/brotli) for the initial JavaScript payload on mobile networks. This equates to roughly 800KB–1MB uncompressed, which can take 3–15 seconds to parse on a mid-range Android device. For Total Blocking Time (TBT) to stay below 300ms, you should keep all long tasks under 50ms. HTTP Archive data shows top-performing sites keep JS under 150KB; median sites ship 450KB+.

Every KB of JavaScript must be parsed and compiled by the browser's JS engine before it can execute. Parse time depends on CPU speed, not network speed — a 200KB JS bundle that downloads in 0.1s on 5G still takes ~500ms to parse on a low-end Android phone. This is why bundle size matters even on fast connections. Use code splitting, tree shaking, and dynamic imports to reduce the initial parse cost. Prefer smaller, lazily-loaded chunks.

Uncompressed size is the raw file size on disk. Compressed size (gzip or brotli) is what gets transferred over the network — typically 60–80% smaller. JavaScript and CSS compress very well; images do not (they're already compressed). Always check compressed sizes for performance budgets, since that's what users actually download. Brotli compresses 10–25% better than gzip and is supported by all modern browsers and CDNs.

Several tools automate this: size-limit (npm) — define budgets in package.json and fail CI if exceeded. bundlesize — similar, supports glob patterns. Lighthouse CI — runs Lighthouse in CI and fails on budget violations. Webpack Performance Hints — built into webpack with maxAssetSize and maxEntrypointSize. GitHub Actions + bundlestats-action — posts size diffs on every PR. A common workflow: run bundle analysis on every PR and post a size report as a PR comment.