RFC: Webpack Performance Budgets

Webpack version:
1.10.x and 2.x

Please tell us about your environment:
OSX 10.x / Linux / Windows 10 [all]

Expected/desired behavior:

Highlight at build-time any JavaScript chunks or bundles that are over a size threshold and can negatively impact web performance load times, parse/compile and interactivity. A default performance budget could indicate if total chunk sizes for a page are over a limit (e.g 250KB).


I’d love to see if we could make this a default and offer a config option for opting out 🏃‍♀️ Concern with an opt-in is the folks with the worst perf issues may not know to enable it or use this via a plugin if this suggestion was deferred to one. These folks may also not be testing on mobile devices.

Optionally, highlight where better performance patterns might be helpful:


Current behaviour:

Many of the apps bundled with Webpack that we trace ship a large, single bundle that ends up pegging the main thread and taking longer that it should for webapps to be interactive:

screen shot 2016-10-28 at 1 38 32 pm

This isn’t Webpack’s fault, just the culture around shipping large monolithic bundles. This situation gets particularly bad on mobile when trying these apps out on real devices.

If we could fix this, it would also make it way more feasible for the Webpack + React (or Angular) stacks to be good candidates for building fast web apps and Progressive Web Apps 🔥

What is the motivation / use case for changing the behavior?

I recently dove into profiling a large set (180+) React apps in the wild, based on 470 responses we got from a developer survey. This included a mix of small to large scale apps.

I noted a few common characteristics:

  • 83+%% of them use Webpack for module bundling (17%% are on Webpack 2)
  • Many ship large monolithic JS bundles down to their users (0.5-1MB+). In most cases, this makes apps interactive in well over 12.4 seconds on real mobile devices (see table 1) compared to the 4 seconds we see for apps properly using code-splitting and keeping their chunks small. They’re also far slower on desktop than they should be – more JS = more parse/execution time spent at a JS engine level.
  • Developers either don’t use code-splitting or use it while still shipping down large chunks of JS in many cases. More on this soon.

Table 1: Summary of time-to-interactive scoring (individual TTI was computed by Lighthouse)

Condition Network latency Download Throughput Upload Throughput TTI average React+Webpack app TTI smaller bundles + code-splitting
Regular 2G 150ms 450kbps 150kbps 14.7s 5.1s
Regular 3G 150ms 1.6MBPs 750kbps 12.4s 4s
Regular 4G 20ms 4MBPs 3MBPs 8.8s 3.8s
Wifi 2ms 30MBPs 15MBPs 6s 3.4s

We generally believe that splitting up your work into smaller chunks can get you closer to being interactive sooner, in particular when using HTTP/2. Only serving down the code a user needs for a route is just one pattern here (e.g PRPL) that we’ve seen helps a great deal.

Examples of this include the great work done by Housing.com and Flipkart.com. They use Webpack and are getting those real nice numbers in the last column thanks to diligence with perf budgets and code-splitting 👍.

What impacts a user’s ability to interact with an app?

A slow time to being interactive can be attributed to a few things:

  1. Client is slow i.e keeping the main thread busy 😓 Large JS bundles will take longer to compile and run. There may be other issues at play, but large JS bundles will definitely peg the main thread. Staying fast by shipping the smallest amount of JS needed to get a route/page interactive is a good pattern, especially on mobile where large bundles will take even longer to load/parse/execute/run
  2. Server/backend may be slow to respond
  3. Suboptimal back and forth between the server and client (lots of waterfall requests) that are a sequence of network busy -> CPU idle -> CPU busy -> network idle and so on.

If we looked at tools like performancebudget.io, targeting loading in RAIL’s <3s on 3G would place our total JS budget at a far more conservative 106KB once you factor in other resources a typical page might include (like stylesheets and images). The less conservative number of 250KB is an upper bound estimate.

Code-splitting and confusion

A surprising 58%%+ of responders said they were using code-splitting. We also profiled just this subset and found that their average time to being interactive was 12.3 seconds (remember that overall, the average TTI we saw was 12.4 with or without splitting). So, what happened?

Digging into this data further, we discovered two things.

  • Either folks that thought they were code-splitting actually weren’t and there was a terminology break-down somewhere (e.g maybe they thought using CommonsChunkPlugin to ‘split’ vendor code from main chunks was code-splitting?) 🤔
  • Folks that definitely were code-splitting had zero insight into chunk size impact on web performance. We saw lots of people with chunk sizes of 400, 500…all the way up to 1200KB of script who were then also lazy-loading in even more script 😢


Keep in mind: it’s entirely possible to ship fast apps using JS that are interactive quickly with Webpack – if Flipkart can hit it in under 5 seconds, we can definitely bring this number down for the average Webpack user too.

Note: if you absolutely need a large bundle of JS for a route/page to be useful at all, our advice is to just serve it in one bundle rather than code-split. At an engine level this is cheaper to parse. In most cases, devs aren’t going to need all that JS for just one page/view/route so splitting helps.

What device was used in our lab profiling?

A Nexus 5X with a real network connection. We also ran tests on emulated setups with throttled CPU and network (2G, 3G, 4G, Wifi). One key thing to note is if this proposal was implemented, it could benefit load times for webapps on all hardware, regardless of whether it’s Android or iOS. Fewer bytes shipped down the line = a little more ❤️ for users data plans.

The time-to-interactive definition we use in Lighthouse is the moment after DOMContentLoaded where the main thread is available enough to handle user input . We look for the first 500ms window where estimated input latency is <50ms at the 90th percentile.

Suppressing the feature

Users could opt-out of the feature through their Webpack configuration (we can 🚲 🏠 over that). If a problem is that most devs don’t run their dev configs optimized for production, it may be worth considering this feature be enabled when the -p production flag is enabled, however I’m unsure how often that is used. Right now it’s unclear if we just want to define a top-level performanceHints config vs a performance object:

performance: {
   hints: true,
   maxBundleSize: 250,
   warnAtPercent: 80

Optional additions to proposal

Going further, we could also consider informing you if:

  • You weren’t taking advantage of patterns like code-splitting (e.g not using require.ensure() or System.import()). This could be expanded to also provide suggestions on other perf plugins (like CommonChunksPlugin)
  • What if Webpack opted for code-splitting by default as long as you were using System.import() or require.ensure()? The minimum config is just the minimum requirements aka the entry ouput today.
  • What if it could guide you through setting up code-splitting and patterns like PRPL if it detected perf issues? i.e at least install the right Webpack plugins and get your config setup or point you to the docs to finish getting setup?

Thanks to Sean Larkin, Shubhie Panicker, Gray Norton and Rob Wormald for reviewing this RFC before I submitted it.

Author: Fantashit

9 thoughts on “RFC: Webpack Performance Budgets

  1. I like the idea very much. And I would like to stress that depending on the situation the performance budget could be 500KB or maybe just 100KB. This way people can set their perfomance budget and they will be notified as soon as they come close to the limit. Maybe already notify them when they are at about 80%% of the budget.

  2. Love it!

    Just wanted to note a nitpick: I’m red-green colorblind, and have a really hard time seeing the difference between the green and the yellow above. Would be great to have some more-different colors there!

  3. Just wanted to note a nitpick: I’m red-green colorblind, and have a really hard time seeing the difference between the green and the yellow above. Would be great to have some more-different colors there!

    More than happy for us to figure out an alternative color scheme 🙂 Also, glad you like the proposal!

  4. Lots of excellent ideas here and I’m excited for the possibilities.

    I just want to remind everyone that for the 1%% of people who have super-advanced configs, and the 19%% of people who have done the config themselves, there’s a much more important 80%% of people who hardly think about webpack at all and are shipping apps with the default settings they found in some blog post. Tree-shaking and code-splitting might eventually help them, but they have other work to do first.

    I would therefore ponder what are the simplest, easiest-to-get-wrong things we could warn them about. These are probably things people remotely familiar with webpack would never do, and so they likely aren’t on the top of our minds. Some examples:

    • Inline source maps in production build
    • Doesn’t use uglifyjs in production build
    • Doesn’t create a DefinePlugin for process.env==='production'

    Unlike tree-shaking and code-splitting, which may require difficult code changes to work well, these are very simple changes anyone can make and get an immediately benefit. And helping non-experts get easy wins (“Wow, I paid attention to this and reduced my load time by half!”) might be a great way to get them excited about worrying about performance more regularly. (I can see a future where, after webpack sees them respond to these initial problems and get a win, it links them to lighthouse or some other tool where they can learn more about performance practices.)

    A lot of the biggest-impact checks should only run in a production build. Which raises another question: since production builds may only run in CI or on a build server, where people rarely look at the logs, should obvious problems like this return an exit code? It could prompt the developer to either fix the problem or modify their performance options to accept the issue.

  5. Does it sound like and idea to try and get prod and Dev configs into a single file?

    You can already achieve that using an external solution. I wrote webpack-merge to cover that need and you can find a plenty of other flavors with a bit of digging. I’m not sure if something like this belongs to webpack core, though. Maybe better leave to user space. 👍

  6. I don’t think this having this enabled for the development environment is constructive. I’m using unminified source files, so it’s obvious the size will be huge. I literally can’t do anything about it, except disable it. The warning isn’t actionable. If warnings are not immediately actionable they’ll just end up being ignored. That makes me think it’s not a good default.

    Just pulling in react and react-dom will push you up to ~750KB. Pulling in one of webpack user’s most popular libraries is enough to push you almost three times over the limit. Using ace editor? If I recall correctly, pulling in brace will bump your bundle size by 600KB.

    I’m worried this is going to be very demotivational for people picking up webpack for the first time. They’ll use create-react-app and immediately get a bunch of warnings without having done anything. That’s not doing webpack’s UX any favors.

    I think the 250KB default is unrealistic for many teams and developers, considering the current state of the ecosystem. This seems to assume that everyone is targeting mobile, which I’d wager is not the case for many web developers. Many complex web apps don’t target mobile at all. What if I’m just creating a test bundle? There’s many situations in which generating a larger bundle is okay.

    My preference would be to have this disabled completely until there’s better documentation and examples available. I’m not aware of any examples that showcase a fully-featured production setup. Getting everything setup and working correctly across environments (dev, testing, building) while combining the use of multiple common libraries is very tricky to get right.

  7. About the phrasing itself, how about using the resulting filesize to show how long it would take to download on a slow connection ? Like “X Mb would take Y minutes to download on a 3G connection” is a straightforward way to onboard developers to reduce the filesize.

  8. This is causing such a tumultuous inner turmoil (over-exaggerating) for me in the direction of this featurex. I have a few conflicting views/opinions.

    It really is spammy and not accurate for dev env

    This makes sense to me, even working on it myself, and even though it could help me catch size bloat early on in bundles, I can only imagine what this is like jumping in a legacy application etc.

    We should really be advocating for better web performance.

    We as an organization are really gravitating to the center of 80-90%% of tooling for web application development. Stats like “50%% of people bounce a mobile page when it takes longer than 3 seconds to load” make me think, “OMG such a great opportunity to increase the awareness across the board and really help people”.

    Can we do both, but create a really easy path to turn off the feature?

    What if we provided very clear and easy steps (terminal command), or URL to docs page showing exactly how to turn off feature for development environments?

    I really really want people to at least know and see the warning at least once, and if they never want to see it again, then we can at least have the assurance that we did what we could to better advocate pushing web performance and awareness together.

    And then we can give a direct link to https://webpack.js.org/configuration/performance/#performance-hints with even a specific hint.

  9. I’d much rather have this as a tool I can use to optimize my builds for performance when I am ready to do that.

    To get an app booting and functioning is frustrating enough without getting constant warnings about your app being suboptimal. I already know my app is suboptimal, I just started making it. It doesn’t have to be optimal, it has to work.

    The first time I saw this warning, I didn’t want to optimize my build, I just wanted to make the warning go away. I’m sure it’s going to be useful when I want to optimize my build, but I just need my app to work and for Webpack to get out of the way.

    This feels like the Webpack equivalent of Clippy:

    I see you’re trying to build without code-splitting, did you know that code-splitting is great? You should totally do it!

Comments are closed.