Bundle size is the amount of browser-delivered JavaScript in a bundled payload. It is a high-impact web performance metric because script must download, parse, and execute before people can use dependent features. Large bundles can therefore delay interaction by seconds on poor mobile networks and harm conversions. section 6.2.2
Measure a transfer budget with compressed size, since gzip or Brotli bytes are what travel over the network. Keep uncompressed size in view as well: the expanded code still creates parsing and execution work after download. A 200KB compressed bundle can expand to roughly 700KB and take close to a second to parse on a mid-range device. section 6.2.2
Table 6.1 Russell’s performance budget baselines
|
Page type
|
Example
|
JavaScript share
|
Total budget (3s load)
|
|
JavaScript-heavy
|
SPAs, client-rendered apps
|
50%
|
1.2MB
|
|
JavaScript-light
|
Server-rendered sites
|
15%
|
2.0MB
|
Use the baseline table to distinguish JavaScript-heavy pages from JavaScript-light pages when setting a three-second load budget. JavaScript-heavy applications need stricter limits because each script byte has processing cost beyond transfer. section 6.2.2
Treat bundle size as an enforced budget rather than a number checked after a regression:
- Measure the current baseline before choosing a threshold; a threshold without data is only a guess. section 6.9
- Set explicit headroom so a new dependency, such as a charting library, must justify its cost, be replaced, load only when needed, or prompt a budget change. section 6.1
- Start with a global budget, then add per-page or per-feature limits where user impact varies; assign owners for ordinary decisions and exceptions. section 6.9
- Review thresholds regularly, document changes and rationale, and reset with a phased plan or larger redesign when drift is too severe for incremental trimming. section 6.8
Keep route-only code out of the main bundle
A rich text editor used only on an internal authoring route was imported into a news site's main bundle, so article readers downloaded it unnecessarily. The regression surfaced later as a 1.4-second mobile slowdown. Bundle visualization identifies which modules caused growth; the remedy is to examine the import strategy before merging rather than treating a total-size increase as an unexplained number. section 8.1 section 8.1.3
Listing 8.5 Configuring webpack to warn when bundle size exceeds a threshold
module.exports = {
performance: {
maxAssetSize: 250000, #A
maxEntrypointSize: 250000, #B
hints: 'warning' #C
}
};Configure webpack to warn when an asset or entrypoint crosses a defined threshold. For ongoing visibility, compare size changes over time with tools such as size-limit, or inspect Vite's default gzipped chunk output before merging. section 8.1.3
Track the trend, not only the latest snapshot. Small additions accumulate invisibly; a budget makes each increase visible and forces an explicit value-versus-cost decision. An intentional increase can be acceptable, but an unnoticed one leaves the team without control of the trajectory. section 6.1 section 8.1.3
