How to set route-level JavaScript limits, account for third parties and make performance trade-offs during planning.
Budget the route, not the repository
A repository can contain megabytes without sending all of them to a visitor. The useful unit is transferred, parsed and executed JavaScript for a particular route and state. Define an initial budget for the first meaningful task, then a separate budget for code loaded after a deliberate interaction. The practical review should record the route, device class, network assumption, cache state and consent state. Teams should keep a baseline trace and a short decision log, because otherwise a later improvement cannot be separated from traffic mix or infrastructure change. The safest implementation is usually the one that reduces hidden work and leaves a clear fallback. Review it at an intermediate viewport as well as desktop and mobile, then repeat the primary task with keyboard input and a cold cache. Capture the result in a form that another engineer can reproduce without access to the original conversation. Include observed evidence, rejected alternatives, operational risk and the signal that triggers rollback. After release, compare both fast and slow percentiles; a median improvement can conceal a worse experience for visitors on constrained devices. Revisit the decision when product behaviour, vendors or traffic distribution changes, because a sound budget is a maintained boundary rather than a one-time audit artifact.
Tie kilobytes to user work
A 200 KB library may be justified in an editing surface and wasteful on a pricing page. Describe the user action enabled by each substantial dependency. If the dependency does not support the route’s primary task, move it behind intent, replace it with platform APIs or remove it. The practical review should record the route, device class, network assumption, cache state and consent state. Teams should keep a baseline trace and a short decision log, because otherwise a later improvement cannot be separated from traffic mix or infrastructure change. The safest implementation is usually the one that reduces hidden work and leaves a clear fallback. Review it at an intermediate viewport as well as desktop and mobile, then repeat the primary task with keyboard input and a cold cache. Capture the result in a form that another engineer can reproduce without access to the original conversation. Include observed evidence, rejected alternatives, operational risk and the signal that triggers rollback. After release, compare both fast and slow percentiles; a median improvement can conceal a worse experience for visitors on constrained devices. Revisit the decision when product behaviour, vendors or traffic distribution changes, because a sound budget is a maintained boundary rather than a one-time audit artifact.
Include execution cost
Compression reduces transfer but not parse and execution cost. Track long tasks, total blocking time in controlled tests and INP in the field. A compact bundle that builds a large component tree can feel slower than a larger bundle with little startup work. Budgets need both bytes and main-thread time. The practical review should record the route, device class, network assumption, cache state and consent state. Teams should keep a baseline trace and a short decision log, because otherwise a later improvement cannot be separated from traffic mix or infrastructure change. The safest implementation is usually the one that reduces hidden work and leaves a clear fallback. Review it at an intermediate viewport as well as desktop and mobile, then repeat the primary task with keyboard input and a cold cache. Capture the result in a form that another engineer can reproduce without access to the original conversation. Include observed evidence, rejected alternatives, operational risk and the signal that triggers rollback. After release, compare both fast and slow percentiles; a median improvement can conceal a worse experience for visitors on constrained devices. Revisit the decision when product behaviour, vendors or traffic distribution changes, because a sound budget is a maintained boundary rather than a one-time audit artifact.
Treat third parties as product dependencies
Analytics, chat, experiments and consent scripts compete for the same network and CPU. Assign an owner, purpose and expiry review to each one. Load by consent and interaction where possible. If a vendor changes its payload without notice, your release gate should expose the regression. The practical review should record the route, device class, network assumption, cache state and consent state. Teams should keep a baseline trace and a short decision log, because otherwise a later improvement cannot be separated from traffic mix or infrastructure change. The safest implementation is usually the one that reduces hidden work and leaves a clear fallback. Review it at an intermediate viewport as well as desktop and mobile, then repeat the primary task with keyboard input and a cold cache. Capture the result in a form that another engineer can reproduce without access to the original conversation. Include observed evidence, rejected alternatives, operational risk and the signal that triggers rollback. After release, compare both fast and slow percentiles; a median improvement can conceal a worse experience for visitors on constrained devices. Revisit the decision when product behaviour, vendors or traffic distribution changes, because a sound budget is a maintained boundary rather than a one-time audit artifact.
Make exceptions explicit
Sometimes a launch requires a temporary overage. Write down the owner, measured impact, removal date and fallback. An invisible exception becomes the new baseline; a visible exception remains a decision. Review budgets at route creation, design review and pull request—not only after launch. The practical review should record the route, device class, network assumption, cache state and consent state. Teams should keep a baseline trace and a short decision log, because otherwise a later improvement cannot be separated from traffic mix or infrastructure change. The safest implementation is usually the one that reduces hidden work and leaves a clear fallback. Review it at an intermediate viewport as well as desktop and mobile, then repeat the primary task with keyboard input and a cold cache. Capture the result in a form that another engineer can reproduce without access to the original conversation. Include observed evidence, rejected alternatives, operational risk and the signal that triggers rollback. After release, compare both fast and slow percentiles; a median improvement can conceal a worse experience for visitors on constrained devices. Revisit the decision when product behaviour, vendors or traffic distribution changes, because a sound budget is a maintained boundary rather than a one-time audit artifact.
A workable starting point
For a content route, start with roughly 150–250 KB compressed first-party JavaScript and a strict third-party allowance, then adjust using the audience’s devices and product needs. The number is a guardrail, not a universal truth. The important part is measuring the same boundary consistently. The practical review should record the route, device class, network assumption, cache state and consent state. Teams should keep a baseline trace and a short decision log, because otherwise a later improvement cannot be separated from traffic mix or infrastructure change. The safest implementation is usually the one that reduces hidden work and leaves a clear fallback. Review it at an intermediate viewport as well as desktop and mobile, then repeat the primary task with keyboard input and a cold cache. Capture the result in a form that another engineer can reproduce without access to the original conversation. Include observed evidence, rejected alternatives, operational risk and the signal that triggers rollback. After release, compare both fast and slow percentiles; a median improvement can conceal a worse experience for visitors on constrained devices. Revisit the decision when product behaviour, vendors or traffic distribution changes, because a sound budget is a maintained boundary rather than a one-time audit artifact.
Working checklist
- Name the route, audience and primary task.
- Record cold and warm states.
- Identify the earliest controllable cause.
- Ship a reversible change with an owner.
- Compare the same field population after release.