Webpack Performance Budgets

Addy Osmani
Published in
3 min readDec 15, 2016


Webpack 2.2 RC includes support for Performance Budgets — a new feature that will help warn (or optionally error) when the size of your JavaScript bundles may be large enough to impact your user experience. The feature is completely configurable, and we hope it will help you ship faster sites 🚕💨

Two hints from Performance Budgets highlighting large entry point scripts & opportunities for using code-splitting

Larger bundles of script can exhibit a few interesting characteristics:

  • They can keep the main browser thread pegged for longer than smaller bundles 😓. This can heavily impact how soon a page is interactive.
  • They can increase the overall load time for a page, keeping your users waiting for an experience that could be complete sooner.
  • They can take longer for a JavaScript engine to parse and compile. This is true on desktop but even moreso on constrained mobile hardware.

When we profiled a few thousand production sites using Webpack 1, we noticed quite a few folks were shipping down monolithic JavaScript bundles between 1–3MB in size (gzipped). This led to unexpectedly slow load times and many sites took up to 20s before they were interactive ⏳

Performance Budgets should help us all get a little more thoughtful with how we much JS we load. This will hopefully lead to faster sites 👍

We care enough about this problem that we’ve made the feature an opt-out. We know it will mean one more thing we all need to keep an eye on, but in the grander scheme of things, if it results in your users getting a happier, faster loading experience, then it’s a win 🏅

Completely configurable

By default, Webpack prescribes some default performance budgets (for entry points and assets). These defaults are based on studies we’ve done into budgets that ultimately lead to a quick loading experience on both cable and 3G.

If, however, you’d like to tweak these defaults, then you can customize the maxAssetSize, maxEntryPointSize or hints (false, ‘warning’ or ‘error’) using a performance entry in your Webpack config:

performance: {
maxAssetSize: 100000,
maxEntrypointSize: 300000,
hints: 'warning'

We know that not every site is the same. Occasionally, your architecture may require a larger (or smaller) bundle to load before it’s useful. We hope the above is flexible enough to meet these needs. If you really, really need to, setting hints to false will suppress the performance suggestions.

Highlighting loading patterns

Where possible, we believe it’s a good pattern to only load features a user is going to need for a page. This means shipping the minimal amount of script to make a page functional, lazy-loading the rest of your scripts for other features or components as the user needs them.

For this reason Performance Budgets also try to encourage using Webpack’s code-splitting, where we think it will make a difference.

Btw, the RC also includes our shiny new support for dynamic import()!

It’s a wrap! 🎁

That’s it! Please try Performance Budgets out, and if you have any feedback on how we can improve the UX for this feature, please, feel free to drop us a comment on this issue thread.

I’d like to take this opportunity to thank Sean Larkin, Sokra, Vignesh Shanmugam and the rest of the Webpack team for the hours poured into making my RFC for this feature a reality.



Addy Osmani

Head of Google Chrome Developer Experience