JavaScript Bundle Analyzer Guide: See What Is Inside Your Bundle

A JavaScript bundle is a single file, or a few files, assembled from an application's own code plus its libraries. Bundles grow quietly. A library is added for one feature, another for a date picker, another for charts, and each addition lands in the bundle whether or not its full power is used. The result is a file that visitors download and the browser parses before the page becomes interactive, and nobody quite knows what is inside it. A bundle analyzer answers that question visually and numerically.

The JavaScript Bundle Analyzer tool summarises pasted bundle size data: the total size, the largest modules, and their shares of the total. The key insight of any bundle report is the share: a module's size divided by the total, which shows where the weight actually lives. A bundle is rarely heavy everywhere; it is usually heavy in a few places, and those places are the only ones worth attacking. A 50 kilobyte module in a 100 kilobyte bundle is half the problem, while the same module in a 2 megabyte bundle is a footnote.

Bundles grow through several mechanisms. Importing a whole library when only one function is used pulls in the rest. Duplicate dependencies, where two versions of the same library ship together, double-count weight. Polyfills for old browsers add code modern browsers never need. Large data files embedded as code, such as locale data for every language when only one is used, inflate the bundle silently. Each mechanism has a different remedy, which is why the report must be read before acting: the remedy for an unused library is removal, for a duplicated dependency is deduplication, and for an oversized locale is importing only the needed language.

A worked example you can follow

Suppose a bundle totals 800 kilobytes, and the report lists four parts: the application code at 200 kilobytes, a chart library at 300 kilobytes, a date library at 180 kilobytes, and miscellaneous utilities at 120 kilobytes. The shares are: application 200 divided by 800, which equals 25 percent; charts 300 divided by 800, which equals 37.5 percent; dates 180 divided by 800, which equals 22.5 percent; utilities 120 divided by 800, which equals 15 percent. The chart library is the largest single part, so it is the first candidate for action.

Suppose charts appear on only one page in ten, and the library can be loaded lazily, only when that page is visited. Removing it from the main bundle reduces the main bundle to 800 minus 300, which equals 500 kilobytes, a saving of 37.5 percent on every page load, while the chart page loads the library on demand. Next, suppose the date library is used for a single formatting function, and replacing it with a small hand-written function removes 170 of its 180 kilobytes. The main bundle falls to 500 minus 170, which equals 330 kilobytes. The combined saving is 800 minus 330, which equals 470 kilobytes, or 470 divided by 800, multiplied by 100, which equals 58.75 percent smaller. Two targeted changes, guided by the shares, more than halved the bundle.

After changing, re-analyse to confirm the new total and to catch regressions, since a removed library sometimes returns through another dependency. The JavaScript Minify tool shrinks the remaining code further, and the Compression Savings Estimator tool estimates the transfer size after compression.

Common mistakes to avoid

The first mistake is optimising the application code while ignoring a library that dominates the bundle. The second is removing a library without checking every import of it, which breaks features that used it quietly. The third is splitting bundles without measuring, which can increase total downloads if shared code is duplicated across splits. The fourth is analysing a development bundle, which is larger and structured differently from the production bundle visitors receive. The fifth is treating bundle size as the only metric, when parse and execution time on slow devices matter as much as download time.

For background on page weight as a whole, see Website SEO Audit Guide. Analyse the bundle, read the shares, attack the largest parts first, and re-analyse after every change. What gets measured gets smaller; what stays invisible keeps growing.

Splitting strategies after analysis

Once analysis shows what a bundle contains, the next decision is how to split it. Route-based splitting loads only the code for the page the visitor is on, which is the highest-value split for most applications, since visitors rarely visit every page. Vendor splitting separates library code, which changes rarely, from application code, which changes often, so returning visitors reuse the cached library file while downloading only the changed application code. Lazy loading goes further: code for features the visitor may never use, such as a settings panel or an export dialog, loads only when that feature is opened, so its weight never burdens visitors who never need it.

Each strategy has a cost that analysis helps weigh. Splitting creates more files and more requests, and if the splits are too fine-grained, the request overhead can exceed the saving. Duplicated shared code across splits can increase total downloads, since a module used by two splits may ship twice unless the bundler is configured to share it. The analyzer reveals duplication, which is the signal to adjust the split boundaries or the shared-chunk configuration. A good split is therefore not the finest possible split but the one where the measured saving, after accounting for duplication and requests, is largest for the most common visitor journeys.

Monitoring completes the practice. Bundles regrow, as new libraries arrive and features accumulate, and a bundle that was 330 kilobytes after optimisation can drift back to 800 kilobytes within a year without anyone noticing. A size budget, checked in the build, turns that drift into a visible failure: when a change pushes the bundle over budget, the build warns or fails, and the author decides consciously whether the new weight is worth it. Without a budget, growth is silent, and silent growth is how bundles became a problem in the first place.