Why your bundle size needs a watchdog

Webpack gathers every imported file into one or more output bundles. That convenience has a cost: as the app grows, so do the bundles, and with them the time users spend waiting for the initial load. Webpack can act as a guardrail here, letting you define performance budgets based on asset size so oversized bundles are flagged before they become a problem.

A typical setup might use React with a utility library like moment.js. In a production build, webpack’s default performance checks will already be active. Run the build from the console and the output will include a color-coded list of assets:

webpack

When a bundle exceeds the default threshold, it is highlighted in yellow with a corresponding warning. The default limit is 244 KiB uncompressed, applied both to individual assets and to entry points (the combined assets needed for the initial page load). These warnings are on by default in production mode, and webpack also hints at strategies for shrinking oversized bundles.

Defining your own thresholds

The default budget is a generic starting point, not a target. A commonly cited rule of thumb for good performance is keeping critical-path resources under 170 KB of compressed/minified output, but your project may warrant a stricter number.

For a small demonstration app, a tighter budget of 100 KB (97.7 KiB) is a reasonable test. In webpack.config.js, this is configured as follows:

module.exports = {
  //...
  performance: {
    maxAssetSize: 100000,
    maxEntrypointSize: 100000,
    hints: "warning"
  }
};

Values are set in bytes:

  • maxAssetSize — the limit for any single asset (here, 100000 bytes)
  • maxEntrypointSize — the limit for the entry point’s total assets (also 100000 bytes)

When the bundle is also the sole entry point, both limits apply to the same output. The hints option controls what happens when a limit is crossed:

  1. warning (default) — shows a yellow warning but the build succeeds; suits development.
  2. error — shows a red error, though the build still passes; better for production builds.
  3. false — suppresses warnings and errors entirely.

Getting back under budget

Warnings exist to catch regressions early, not to block work forever. When a budget is exceeded, the fix often involves looking at the weight of third-party dependencies. Frameworks are convenient but hard to swap out late in a project; the same cannot always be said for utility libraries.

Moment.js, for instance, is a frequent source of bloat. Its functionality can often be replicated with a small amount of vanilla JavaScript. Removing the library and reimplementing the date logic directly is one fast path:

const today = new Date();
const year = today.getFullYear();
const yearEnd = new Date(year,11,31); //months are zero indexed in JS
const timeDiff = Math.abs(yearEnd.getTime() - today.getTime());
const daysLeft = Math.ceil(timeDiff / (1000 * 3600 * 24));

After deleting the import line and removing the package from package.json, rebuilding produces a much smaller bundle. In the source example, this cut roughly 223 KiB (230 KB) and brought the app comfortably below the custom threshold.

A budget is only useful if it’s checked

The appeal of a webpack performance budget is that it requires no manual oversight. With a few lines of configuration, the build process continuously flags accidental additions of heavy dependencies, keeping performance implications visible without extra effort.