Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 38 ยท Optimization and Caching

Bundle Analysis and Performance Budgets

Find what bloats your webpack bundle: stats.json, webpack-bundle-analyzer, performance hints and budgets, duplicate packages, and a repeatable size-reduction routine.

You cannot shrink what you cannot see. Bundle analysis turns the opaque dist folder into a map of who contributes how many bytes. Usually the result is humbling: one date library, one icon set or a duplicated copy of a package accounts for half the weight. This lesson shows how to produce the data, read it, set performance budgets that fail the build when size creeps up, and follow a routine for reducing size.

The analyzer tools are not runnable on this site, so configs and commands are read-only. The TryIt blocks are Node.js stand-ins that process a fake stats object the way the real tools do: sum sizes, rank them, find duplicates and check a budget.

Getting the data

Webpack can write a JSON description of the whole build, called stats:

Terminal
npx webpack --mode production --profile --json=stats.json

The file lists every chunk, every module with its size, and why each module was included (the importer chain). Many tools read it, including the online analyzers and webpack-bundle-analyzer:

JavaScript
// webpack.config.js (read-only example)
const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer');

module.exports = {
  plugins: [
    new BundleAnalyzerPlugin({
      analyzerMode: process.env.ANALYZE ? 'static' : 'disabled',
      reportFilename: 'report.html',
      openAnalyzer: false,
    }),
  ],
};

Run ANALYZE=1 npx webpack and open report.html: a treemap in which every rectangle is a module, sized by bytes. Three size numbers are shown, and you should know the difference:

  • Stat size: the raw source size before any processing.
  • Parsed size: the size in the output file after minification. This is closest to what the browser parses.
  • Gzip size: what travels over the network when compression is on.

Reading a stats object

Here is a stand-in that takes a simplified stats structure and ranks packages by their parsed size. Real stats have the same idea with more fields.

Node.js Stand-in: rank packages by size

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Seeing moment at the top, with locale files that nobody asked for, is a classic finding. The fix might be IgnorePlugin for locales, or switching to a smaller date library.

Typical findings and fixes

Finding Likely fix
A whole utility library for a few functions Import individual functions, use the ES build (lodash-es) and check tree shaking
Two versions of the same package Deduplicate with the package manager (npm dedupe) or resolve.alias
Large locale or icon sets Import only what is used; IgnorePlugin for locales
A heavy library on every page Move to a dynamic import
Polyfills for browsers you do not support Tighten browserslist
Source maps in production bundles Use a non-inline devtool

Duplicate packages

Two copies of one package can appear when different dependencies need incompatible versions. The stand-in below finds them from a list of resolved paths.

Node.js Stand-in: detect duplicate packages

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Performance budgets

Analysis finds problems once; a budget keeps them from coming back. Webpack has built-in hints:

JavaScript
module.exports = {
  performance: {
    hints: 'error',             // 'warning' (default in production) or false
    maxEntrypointSize: 250000,  // bytes of everything an entry loads
    maxAssetSize: 200000,       // bytes of any single file
    assetFilter: (file) => file.endsWith('.js'),
  },
};

With hints: 'error' the build fails when a limit is exceeded, so a pull request that adds a heavy dependency is caught in CI. Budgets use uncompressed sizes by default, so pick numbers with that in mind. Larger teams add a check for gzip size with tools such as size-limit.

Node.js Stand-in: a budget check for CI

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

A repeatable routine

  1. Build for production and generate the report.
  2. Sort by parsed size and look at the top five packages.
  3. For each, ask: needed at start-up? Can it be lazy? Is there a lighter alternative?
  4. Check for duplicates and unused polyfills.
  5. Re-measure, record the numbers, and set a budget slightly above the new size.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which size in the bundle analyzer is closest to what the browser must parse?

    Parsed size is the minified size in the output file. Gzip size is the network transfer size.
  2. 2. What does performance.hints: 'error' do?

    With 'error' an exceeded budget becomes a build failure, which makes it useful in CI.
  3. 3. You find two copies of the same package in the bundle. What is a good first step?

    Duplicates come from incompatible version ranges. Aligning versions or running dedupe usually removes them.
  4. 4. How do you generate stats for analysis tools?

    The --json flag writes the build statistics to a file that analyzers can read.

Summary

  • Generate stats.json or a treemap report to see where bytes come from.
  • Compare stat, parsed and gzip sizes; parsed size matters most for CPU, gzip for network.
  • Typical wins: lazy-load heavy libraries, fix duplicates, import less, trim polyfills.
  • Set performance budgets so regressions fail CI.

Next: Webpack with React