Bundle Analysis

## What a bundle treemap actually is When a bundler finishes a build it knows exactly which modules it pulled into each output chunk and how many bytes each contributed. A treemap analyzer takes that record and draws it: the whole canvas is one chunk (or the whole output), and every module inside it becomes a rectangle whose **area is proportional to its byte contribution**. Rectangles are nested by path, so `node_modules/lodash/*` forms one block, your `src/routes/*` forms another. The visual point of a treemap is that size differences that are invisible in a text list — a 400 kB dependency next to two hundred 2 kB source files — become impossible to miss. This is why analysis comes before cutting. Teams that guess at what is heavy almost always guess wrong; they micro-optimise their own components while one date library, one icon set, or one duplicated polyfill accounts for most of the payload. ## Where the data comes from The analyzer is not parsing your shipped files by hand — it reads the build's own statistics record. In webpack that is the JSON stats output; Rollup and Vite expose the equivalent through `rollup-plugin-visualizer`; esbuild writes a metafile that its own online analyzer renders. Two consequences follow: - The report is only as truthful as the build that produced it. A development build has no minification and often extra dev-only code, so a treemap from `pnpm dev` bears little resemblance to production. Always analyze the same command your deploy runs. - Because the record is per chunk, the map also tells you *where* a module landed — main entry, vendor chunk, or a lazily loaded chunk. A dependency being large matters much less when its rectangle sits inside a chunk that only one rarely visited route pulls in. ```bash # webpack: emit the stats record, then render it npx webpack --profile --json > stats.json npx webpack-bundle-analyzer stats.json ``` ## The three sizes, and why the default misleads webpack-bundle-analyzer shows a size selector with three modes, and mixing them up is the most common beginner error: - **stat size** — the size of the module as the bundler read it in, before minification. Useful for seeing how much source a package carries, useless as a user-facing number. - **parsed size** — the module's bytes in the emitted, minified output. This is what the browser must parse and compile. - **gzip size** — the minified bytes after gzip compression. This is the closest available proxy for what actually travels over the network, since servers and CDNs compress text responses. Ranking can change between modes. A package full of long identifiers and comments shrinks dramatically under minification; a package full of large embedded data tables (locale data, emoji tables, country lists) barely shrinks at all and often overtakes it once you switch to gzip. If you make a decision from the default mode without checking, you can spend a week removing something that was already cheap on the wire. ## What the map does not answer A treemap is a static inventory. It says nothing about: - **Execution.** A module can be present and never called. Presence is a size problem; execution is a runtime problem, and they need different measurements. - **Cost in time.** Bytes are correlated with parse and compile time, but a rectangle's area is not a duration. Two equally large modules can differ enormously in how much work they do at startup. - **Removability.** A big rectangle is a *candidate*, not a verdict. Whether it can go depends on who imports it and whether an equivalent lighter path exists. - **What the user downloaded.** The map describes build output. A returning visitor with a warm cache, or a visitor on a route that never loads that chunk, downloads something different. ## Reading one in practice A useful first pass takes about two minutes. Switch to gzip sizes. Look at the top three rectangles by area and name them out loud. Ask, for each, which chunk it is in and whether that chunk is needed for the first screen. Then look for the same package name appearing in two places — a strong hint of a duplicate — and for a package you only meant to use one function from that has arrived whole. Those four observations, in that order, cover most of what a first bundle investigation finds. Everything after that — deciding what to remove, where to split, what limit to enforce — is a separate decision. The map's job is to make sure the decision is about the right module.