Bundle Analysis and Optimization

You're Probably Shipping More JavaScript Than You Think

Here's a reality check: the median JavaScript payload for a modern web app is about 500KB compressed. On a 3G connection, that's 3-5 seconds just to download — before the browser even starts parsing and executing. And most of that JavaScript? Your users never need it for the page they're on.

Bundle analysis turns a black box into a transparent map. Once you see what's inside your bundle, the optimizations become obvious.

The Analysis Toolbox

webpack-bundle-analyzer / @next/bundle-analyzer

The gold standard. Generates an interactive treemap where each rectangle's area corresponds to the module's size.

// next.config.js (Next.js)
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
});

module.exports = withBundleAnalyzer({});

ANALYZE=true pnpm build

The treemap shows three size metrics:

• Stat size — raw size before processing (rarely useful)
• Parsed size — size after minification (CPU cost: the browser must parse and execute this)
• Gzip size — size after compression (network cost: what actually downloads)

Always focus on parsed size for execution cost and gzip size for download cost.

source-map-explorer

Uses source maps for precise byte-level attribution. More accurate than webpack-bundle-analyzer for understanding which specific source files contribute the most bytes.

npx source-map-explorer .next/static/chunks/main-*.js

bundlephobia.com

Check the cost of any npm package before you install it:

• Bundle size (minified + gzipped)
• Download time on 3G
• Whether it's tree-shakable
• Full dependency tree

Import Cost (VS Code extension)

Shows the import cost inline in your editor as you type:

import { debounce } from 'lodash';        // 72KB
import debounce from 'lodash/debounce';    // 1.2KB
import { debounce } from 'lodash-es';      // 1.5KB (tree-shakable)

Tree Shaking Verification

Tree shaking sounds great in theory. But how do you verify it's actually working?

The Single-Import Test

// test-shake.js
import { oneFunction } from './my-library';
console.log(oneFunction());

Build this, then check the output size. If my-library exports 50 functions and your bundle is significantly larger than the one function you imported, tree shaking is failing.

Common Tree Shaking Failures

1. Missing sideEffects: false in package.json — the bundler conservatively includes all modules
2. CommonJS format — require() can't be statically analyzed
3. Barrel files with side effects — index.ts re-exports trigger inclusion of all re-exported modules
4. Top-level function calls — registerComponent() at module scope is a side effect

{
  "name": "my-library",
  "sideEffects": false
}

Adding sideEffects: false to your library's package.json tells bundlers: "if exports from these modules aren't used, the entire module can be safely dropped."

Duplicate Dependency Detection

One of the most common sources of bundle bloat: the same library included at different versions because different packages depend on different versions.

# Find duplicate packages
npm ls lodash
# or
pnpm why lodash

my-app
├── lodash@4.17.21
├── package-a
│   └── lodash@4.17.15
└── package-b
    └── lodash@4.17.20

Three copies of lodash. That's ~216KB of wasted space.

Fixes:

// package.json — npm overrides
{
  "overrides": {
    "lodash": "4.17.21"
  }
}

// package.json — pnpm overrides
{
  "pnpm": {
    "overrides": {
      "lodash": "4.17.21"
    }
  }
}

# Deduplicate compatible versions
npm dedupe

Barrel File Cost Analysis

Barrel files (index.ts that re-export everything) are one of the biggest silent bundle killers:

// src/components/index.ts — the barrel
export { Button } from './Button';
export { Modal } from './Modal';         // imports framer-motion (60KB)
export { DataTable } from './DataTable'; // imports tanstack-table (50KB)
export { Chart } from './Chart';         // imports recharts (150KB)

// Your page — only needs Button (2KB)
import { Button } from '@/components';
// But you might get Button + framer-motion + tanstack-table + recharts = 262KB

The fix: Import directly from the source module.

import { Button } from '@/components/Button';

To audit barrel file impact:

1. Find all barrel imports in your codebase (imports from directories or index files)
2. Build with the barrel import, note the bundle size
3. Change to a direct import, rebuild, compare
4. If the direct import is significantly smaller, the barrel is leaking

Setting Performance Budgets

A budget is a maximum allowed size for your JavaScript bundles. Without one, bundle size creeps up with every new feature and dependency until someone notices the app is slow.

webpack Budget Configuration

module.exports = {
  performance: {
    maxAssetSize: 250000,
    maxEntrypointSize: 250000,
    hints: 'error',
  },
};

Bundlesize / size-limit

// package.json
{
  "size-limit": [
    { "path": "dist/index.esm.js", "limit": "15 KB" },
    { "path": "dist/index.cjs.js", "limit": "18 KB" }
  ]
}

npx size-limit

Run this in CI. If a PR pushes the bundle over budget, the build fails. This creates the most effective forcing function: developers must actively optimize or reduce scope when they hit the budget ceiling.

Ratcheting Strategy

Don't set an aspirational budget — set one based on your current size:

1. Measure your current bundle sizes
2. Set the budget at current size + 5%
3. When you optimize and shrink the bundle, lower the budget to the new size + 5%
4. Repeat

This prevents regression while avoiding unrealistic targets that everyone ignores.

Optimization Strategies Summary