Javascript Bundle Optimization

When a JavaScript bundle grows beyond a few hundred kilobytes, the cost shifts from developer convenience to user-facing performance. Large bundles increase Time to Interactive, inflate data costs on metered connections, and trigger core web vital regressions. This page is for frontend engineers who need to reduce bundle size, diagnose what’s inflating it, and configure the build pipeline to prevent regression. It matters whenever a new dependency lands, a code path expands, or a performance budget is breached.

Diagnose the current bundle

Before optimizing, you need an accurate picture of what’s inside the output. Modern bundlers provide built-in inspection, but the output format varies.

Webpack includes a bundled-analysis plugin that generates an interactive sunburst view:

# Add as a dev dependency
npm install --save-dev webpack-bundle-analyzer

# Run production build with the plugin
npx webpack --mode production --plugins new (require('webpack-bundle-analyzer')).BundleAnalyzerPlugin

The plugin launches a local server at http://localhost:8888 displaying a rotatable, color-coded breakdown by module size, namespace, and type. Clicking any chunk reveals the contributing modules and their individual footprints.

esbuild offers a simpler, text-based profile:

npx esbuild app.js --bundle --minify --profile=profile.json

The resulting profile.json contains each file’s byte size, gzipped size, and execution time. Pipe it through jq to surface the heaviest entries:

jq -r '.[] | "\(.file) \(.size) \(.gzSize)"' profile.json | sort -nr -k2 | head -20

Both tools reveal the same class of surprises: a single large utility, an un-tree-shaken dependency, or a development-only module shipped into production.

Reduce the initial payload

Once you know what’s inflating the bundle, apply targeted reductions. The most effective levers are tree shaking, minification, and code splitting—each supported by real commands and flags.

Tree shaking

Tree shaking eliminates unused exports at build time. It relies on static analysis and the export/import syntax. Webpack performs tree shaking by default when running in production mode, but the behavior can be fine-tuned:

// webpack.config.js
module.exports = {
  mode: 'production',
  optimization: {
    usedExports: true,
    sideEffects: false
  }
};

Set usedExports: true to enable the plugin that removes exports not referenced elsewhere. Set sideEffects: false only if your package guarantees no side effects from imports; otherwise, list packages with side effects in the sideEffects field of package.json.

esbuild performs tree shaking automatically when bundling, with no additional configuration required.

Minification

Minification removes whitespace, shortens variable names, and inlines simple constants. Both webpack and esbuild integrate minifiers that activate in production mode.

webpack uses TerserPlugin by default:

npm install --save-dev terser-webpack-plugin

The plugin is configured via optimization.minimizer if customization is needed:

optimization: {
  minimizer: [
    new TerserPlugin({
      parallel: true,
      terserOptions: {
        ecma: 2022,
        compress: {
          drop_console: true
        }
      }
    })
  ]
}

esbuild includes a built-in minifier activated with --minify. Additional control is available through flags:

npx esbuild app.js --bundle --minify --minify-whitespace --minify-syntax

The --minify-whitespace flag strips excess whitespace without altering syntax, while --minify-syntax performs more aggressive transformations such as removing unreachable code.

Code splitting

Code splitting defers loading of non-critical modules until needed, reducing the initial bundle. Dynamic import() syntax is the standard mechanism:

// Before: static import
import { heavyCalc } from './heavy-module.js';

// After: dynamic import with fallback
const heavyModule = await import('./heavy-module.js').catch(err => {
  console.error('Failed to load heavy module', err);
});

Webpack treats import() as a split point and generates a separate chunk. The chunk is fetched on demand, and the promise resolves when the script executes.

Route-level code splitting with react-loadable or Loadable.Component follows the same pattern: the component’s code is fetched when the route mounts, not when the app starts.

Configure the build pipeline

Beyond the immediate optimization levers, the build configuration itself can introduce or prevent bloat.

Loader optimizations

Babel and TypeScript compilers can generate larger output than necessary if configured permissively.

Babel in production should drop propTypes and development-only helpers:

// .babelrc
{
  "presets": ["@babel/preset-env"],
  "plugins": [
    ["@babel/plugin-transform-react-remove-prop-types", { "mode": "remove" }],
    "@babel/plugin-transform-react-constants"
  ]
}

@babel/preset-env compiles down to targeted browsers when modules: false is set, preserving ES modules and preventing unnecessary transpilation:

// .babelrc
{
  "presets": [
    ["@babel/preset-env", { "modules": false, "targets": "> 0.25%, not dead" }]
  ]
}

Plugin hygiene

Audit installed plugins regularly. A common source of bundle bloat is a plugin that runs in production without being disabled. Check each plugin’s package.json for sideEffects and peerDependencies; remove any that are no longer used in the codebase.

Source map control

Source maps are essential for debugging but can double or triple bundle size. Exclude them from production artifacts unless explicitly needed:

// webpack.config.js
module.exports = {
  mode: 'production',
  devtool: 'hidden-source-map'
};

hidden-source-map generates a source map file separate from the main bundle, which can be served alongside source files in development but is absent from the shipped artifact.

Visualize and iterate

After applying changes, re-run the inspection commands to confirm reduction. Compare the new sunburst or profile against the baseline. If a chunk grew unexpectedly, inspect the contributing modules—often a new dependency or a recently added feature flag is the culprit.

Iterate by adjusting the configuration, removing unused imports, or splitting larger chunks further. The goal is a bundle that fits within the project’s performance budget without sacrificing functionality.

Sharp edges

Tree shaking false negatives

Tree shaking only removes exports that are statically analyzable. Dynamic import() calls, computed property names, and runtime eval() invocations prevent the optimizer from determining which exports are used. Code that relies on these patterns may not be shaken, even in production.

Minification gotchas

Aggressive minification can rename variables that are referenced via string keys or inspected at runtime. If your code uses for (const key in object) patterns or Object.keys(), the minifier may produce incorrect output. Guard such patterns with /* eslint-disable */ comments or configure the minifier to preserve specific names.

Code splitting pitfalls

Dynamic imports that are hoisted or called in async contexts may not split as expected. If import() appears inside a try/catch or a conditional that the bundler cannot statically evaluate, it may be inlined into the main chunk. Use webpackChunkName comments or esbuild’s --splitting flag to control chunk naming and ensure the split occurs where intended.

Production/build mismatches

A frequent source of regression is developing against a development build and deploying a production build without re-running the full pipeline. Development builds often omit minification and tree shaking, so the local bundle size feels smaller than what users experience. Enforce a CI step that always produces a production artifact before deployment, and compare its size against the budget using a tool like size-limit or webpack-bundle-analyzer in headless mode.

Confused options

sideEffects: false and usedExports: true are independent controls. Setting sideEffects: false tells the bundler it’s safe to remove modules that have no side effects, which can indirectly enable more tree shaking. But usedExports: true specifically targets unused exports within kept modules. Confusing the two leads to either over-aggressive removal (broken imports) or missed opportunities (unused exports remain). Set both when the codebase uses pure functions and side-effect-free modules.

This page was rewritten on 18 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.