Tooling

Build Optimization for Production Bundles

Shane
2/14/2026
17 min read

A practical guide to optimizing JavaScript production bundles covering code splitting, tree shaking, minification, compression, and asset optimization strategies.

javascriptperformancebundlingbuild-optimizationminificationcompression

Build Optimization for Production Bundles

Shipping a 2.5MB JavaScript bundle to production is not a performance problem. It is a business problem. Every 100ms of additional load time costs measurable revenue. On a 3G mobile connection, a 2MB bundle takes over 10 seconds to download, parse, and execute. Users leave. Search rankings drop. Conversion rates collapse.

I have spent years auditing production bundles across dozens of projects, and the pattern is always the same: teams focus on writing code and forget that the build pipeline is where performance is won or lost. This article walks through every meaningful optimization technique I use to take bloated bundles and cut them down to a fraction of their original size, with real configuration and measurable results.

Why Build Optimization Matters

Three forces make bundle optimization non-negotiable:

Load time is money. Amazon found that every 100ms of latency costs 1% in sales. Google penalizes slow sites in search rankings. Your users on mobile networks in emerging markets are not on gigabit fiber.

Bandwidth is finite. Mobile data caps exist. Users on metered connections resent sites that waste their data budget. A well-optimized bundle respects the user's constraints.

Parse and execute time scales with size. JavaScript is not just downloaded — it must be parsed, compiled, and executed. On a mid-range Android phone, parsing 1MB of JavaScript takes 2-4 seconds. That is dead time where the user stares at a blank screen.

Measuring Bundle Size

You cannot optimize what you do not measure. Before touching any configuration, establish a baseline.

webpack-bundle-analyzer

This is the single most useful tool for understanding what is in your bundle:

var BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;

module.exports = {
  plugins: [
    new BundleAnalyzerPlugin({
      analyzerMode: 'static',
      reportFilename: 'bundle-report.html',
      openAnalyzer: false
    })
  ]
};

Run the build and open bundle-report.html. You get an interactive treemap showing every module, its raw size, parsed size, and gzipped size. The first time you do this on a mature project, you will find surprises — duplicate dependencies, entire libraries pulled in for a single function, locale data you never use.

source-map-explorer

For a second opinion, use source-map-explorer. It reads source maps to trace every byte back to its origin:

npx source-map-explorer dist/main.*.js

This catches things the bundle analyzer misses, particularly when modules get concatenated during scope hoisting.

Size budgets

Set hard limits in your build configuration:

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

The build fails if any entry point exceeds 250KB or any single asset exceeds 200KB. This prevents gradual bloat from creeping in unnoticed.

Minification

Terser Configuration

The default Terser settings are conservative. For production, push harder:

var TerserPlugin = require('terser-webpack-plugin');

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        terserOptions: {
          parse: {
            ecma: 2020
          },
          compress: {
            ecma: 5,
            comparisons: false,
            inline: 2,
            drop_console: true,
            drop_debugger: true,
            pure_funcs: ['console.log', 'console.info', 'console.debug'],
            passes: 3,
            toplevel: true,
            dead_code: true,
            collapse_vars: true,
            reduce_vars: true
          },
          mangle: {
            safari10: true,
            toplevel: true
          },
          output: {
            ecma: 5,
            comments: false,
            ascii_only: true
          }
        },
        parallel: true,
        extractComments: false
      })
    ]
  }
};

Key options: passes: 3 runs the compressor three times, catching optimizations that only become possible after earlier passes. drop_console: true strips all console statements. toplevel: true allows mangling of top-level variable names, which is safe for bundles but not for libraries.

CSS Minification

Use css-minimizer-webpack-plugin with cssnano:

var CssMinimizerPlugin = require('css-minimizer-webpack-plugin');

module.exports = {
  optimization: {
    minimizer: [
      new CssMinimizerPlugin({
        minimizerOptions: {
          preset: ['advanced', {
            discardComments: { removeAll: true },
            reduceIdents: false,
            zindex: false
          }]
        }
      })
    ]
  }
};

The advanced preset is more aggressive than the default. I disable reduceIdents and zindex because they can cause subtle visual bugs when CSS ordering matters.

Compression: gzip vs Brotli

Pre-compression

Do not rely on your web server to compress on the fly. Pre-compress during the build:

var CompressionPlugin = require('compression-webpack-plugin');
var zlib = require('zlib');

module.exports = {
  plugins: [
    new CompressionPlugin({
      filename: '[path][base].gz',
      algorithm: 'gzip',
      test: /\.(js|css|html|svg)$/,
      threshold: 1024,
      minRatio: 0.8
    }),
    new CompressionPlugin({
      filename: '[path][base].br',
      algorithm: 'brotliCompress',
      test: /\.(js|css|html|svg)$/,
      compressionOptions: {
        params: {
          [zlib.constants.BROTLI_PARAM_QUALITY]: 11
        }
      },
      threshold: 1024,
      minRatio: 0.8
    })
  ]
};

Brotli at quality 11 produces files 15-25% smaller than gzip at quality 9. The trade-off is compression time — Brotli 11 is slow. But since you compress once at build time and serve many times, this is the right trade-off.

Configure your server (nginx, Express, etc.) to serve the pre-compressed file when the client supports it:

location /static/ {
    gzip_static on;
    brotli_static on;
}

For Express:

var express = require('express');
var expressStaticGzip = require('express-static-gzip');

var app = express();
app.use('/static', expressStaticGzip('dist', {
  enableBrotli: true,
  orderPreference: ['br', 'gz']
}));

Code Splitting Strategies

Code splitting is the highest-impact optimization available. Instead of shipping one monolithic bundle, you split it into chunks that load on demand.

Vendor Chunk Splitting

Separate your dependencies from your application code. Dependencies change rarely; application code changes often. Splitting them means users cache vendor code across deploys:

module.exports = {
  optimization: {
    splitChunks: {
      chunks: 'all',
      maxInitialRequests: 25,
      minSize: 20000,
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: function(module) {
            var packageName = module.context.match(
              /[\\/]node_modules[\\/](.*?)([\\/]|$)/
            )[1];
            return 'vendor.' + packageName.replace('@', '');
          },
          priority: 10
        },
        common: {
          minChunks: 2,
          priority: 5,
          reuseExistingChunk: true
        }
      }
    }
  }
};

This creates a separate chunk per npm package. Large dependencies like lodash or moment get their own cached file. The common group captures code shared by multiple entry points.

Route-Based Splitting

For single-page applications, split by route. Each page loads only the JavaScript it needs:

var routes = [
  {
    path: '/dashboard',
    component: function() {
      return import(/* webpackChunkName: "dashboard" */ './pages/Dashboard');
    }
  },
  {
    path: '/settings',
    component: function() {
      return import(/* webpackChunkName: "settings" */ './pages/Settings');
    }
  },
  {
    path: '/reports',
    component: function() {
      return import(/* webpackChunkName: "reports" */ './pages/Reports');
    }
  }
];

The webpackChunkName magic comment controls the output filename. Without it, you get numbered chunks that are impossible to debug.

Dynamic Imports for Lazy Loading

Heavy components that appear below the fold or behind user interaction should load lazily:

var chartModule = null;

function renderChart(data) {
  if (chartModule) {
    chartModule.render(data);
    return;
  }

  import(/* webpackChunkName: "chart-engine" */ './chartEngine')
    .then(function(mod) {
      chartModule = mod;
      chartModule.render(data);
    });
}

document.getElementById('show-chart').addEventListener('click', function() {
  renderChart(dashboardData);
});

The chart engine only downloads when the user clicks the button. Until then, it costs zero bytes on initial load.

Tree Shaking and Dead Code Elimination

Tree shaking removes unused exports from your bundle. It works by analyzing ES module import/export statements statically.

The sideEffects Flag

In your package.json, declare that your code is side-effect free:

{
  "name": "my-app",
  "sideEffects": [
    "*.css",
    "*.scss",
    "./src/polyfills.js"
  ]
}

This tells webpack that any module not listed can be safely dropped if its exports are unused. CSS files and polyfills are exceptions because they execute side effects on import.

Pure Annotations

For function calls that webpack cannot prove are side-effect free, add the /*#__PURE__*/ annotation:

var result = /*#__PURE__*/ createExpensiveObject();

If result is never used, webpack can safely remove the entire call. This matters for library authors especially.

Scope Hoisting / Module Concatenation

Enable ModuleConcatenationPlugin (on by default in production mode). It merges small modules into a single scope, reducing function call overhead and enabling further minification:

var webpack = require('webpack');

module.exports = {
  plugins: [
    new webpack.optimize.ModuleConcatenationPlugin()
  ]
};

Scope hoisting typically saves 5-10% on bundle size and improves runtime performance.

Asset Optimization

Image Compression

Use image-minimizer-webpack-plugin to compress images at build time:

var ImageMinimizerPlugin = require('image-minimizer-webpack-plugin');

module.exports = {
  optimization: {
    minimizer: [
      new ImageMinimizerPlugin({
        minimizer: {
          implementation: ImageMinimizerPlugin.sharpMinify,
          options: {
            encodeOptions: {
              jpeg: { quality: 80 },
              webp: { quality: 80 },
              png: { compressionLevel: 9 },
              avif: { quality: 65 }
            }
          }
        },
        generator: [
          {
            preset: 'webp',
            implementation: ImageMinimizerPlugin.sharpGenerate,
            options: {
              encodeOptions: {
                webp: { quality: 80 }
              }
            }
          }
        ]
      })
    ]
  }
};

This converts images to WebP (30% smaller than JPEG at equivalent quality) and compresses all formats.

SVG Optimization

SVGO strips metadata, redundant attributes, and simplifies paths:

var ImageMinimizerPlugin = require('image-minimizer-webpack-plugin');

module.exports = {
  optimization: {
    minimizer: [
      new ImageMinimizerPlugin({
        minimizer: {
          implementation: ImageMinimizerPlugin.svgoMinify,
          options: {
            encodeOptions: {
              multipass: true,
              plugins: [
                'preset-default',
                { name: 'removeViewBox', active: false },
                { name: 'removeDimensions', active: true }
              ]
            }
          }
        }
      })
    ]
  }
};

Keep removeViewBox disabled — removing it breaks responsive SVG scaling.

Font Subsetting

If you use custom fonts, subset them to include only the characters you actually need:

@font-face {
  font-family: 'CustomFont';
  src: url('./fonts/custom-latin.woff2') format('woff2');
  font-display: swap;
  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+2000-206F;
}

A full font file might be 200KB. Subsetting to Latin characters typically reduces it to 20-30KB.

CSS Optimization

PurgeCSS

PurgeCSS scans your templates and removes CSS selectors that do not appear anywhere in your markup:

var PurgeCSSPlugin = require('purgecss-webpack-plugin');
var glob = require('glob-all');
var path = require('path');

module.exports = {
  plugins: [
    new PurgeCSSPlugin({
      paths: glob.sync([
        path.join(__dirname, 'src/**/*.html'),
        path.join(__dirname, 'src/**/*.js'),
        path.join(__dirname, 'src/**/*.jsx')
      ]),
      safelist: {
        standard: [/^modal/, /^tooltip/, /^carousel/],
        deep: [/^data-/]
      }
    })
  ]
};

Bootstrap CSS drops from 180KB to 10-20KB after purging. The safelist preserves dynamically added classes that PurgeCSS cannot detect statically.

Critical CSS Extraction

Extract above-the-fold CSS and inline it directly in the HTML:

var CriticalCssPlugin = require('html-critical-webpack-plugin');

module.exports = {
  plugins: [
    new CriticalCssPlugin({
      base: path.resolve(__dirname, 'dist'),
      src: 'index.html',
      dest: 'index.html',
      inline: true,
      minify: true,
      dimensions: [
        { width: 375, height: 667 },
        { width: 1440, height: 900 }
      ]
    })
  ]
};

This eliminates the render-blocking CSS request for initial paint. The remaining CSS loads asynchronously.

Environment-Specific Builds and Differential Loading

Stripping Development Code

Use DefinePlugin to create compile-time constants:

var webpack = require('webpack');

module.exports = {
  plugins: [
    new webpack.DefinePlugin({
      'process.env.NODE_ENV': JSON.stringify('production'),
      __DEV__: false,
      __VERSION__: JSON.stringify(require('./package.json').version)
    })
  ]
};

Any code guarded by if (__DEV__) gets eliminated entirely by dead code removal after Terser sees the constant false.

Differential Loading: Modern vs Legacy Bundles

Ship smaller bundles to modern browsers and a fallback to legacy browsers:

<script type="module" src="/static/js/main.modern.js"></script>
<script nomodule src="/static/js/main.legacy.js"></script>

Modern browsers ignore nomodule scripts. Legacy browsers ignore type="module" scripts. You get polyfill-free, smaller bundles for 90%+ of your traffic.

In webpack, create two configurations:

var baseConfig = require('./webpack.base.js');
var merge = require('webpack-merge').merge;

var modernConfig = merge(baseConfig, {
  output: {
    filename: '[name].modern.[contenthash:8].js'
  },
  target: 'browserslist:modern'
});

var legacyConfig = merge(baseConfig, {
  output: {
    filename: '[name].legacy.[contenthash:8].js'
  },
  target: 'browserslist:legacy',
  module: {
    rules: [{
      test: /\.js$/,
      use: {
        loader: 'babel-loader',
        options: {
          presets: [['@babel/preset-env', {
            useBuiltIns: 'usage',
            corejs: 3,
            targets: '> 0.5%, not dead'
          }]]
        }
      }
    }]
  }
});

module.exports = [modernConfig, legacyConfig];

The modern bundle skips Babel entirely, saving 20-40% in size.

Preload, Prefetch, and Cache Busting

Preload and Prefetch for Split Chunks

Tell the browser to fetch critical chunks early:

<link rel="preload" href="/static/js/vendor.react.a1b2c3d4.js" as="script">
<link rel="prefetch" href="/static/js/dashboard.e5f6g7h8.js">

preload fetches immediately with high priority (use for chunks needed on current page). prefetch fetches during idle time (use for chunks likely needed on next navigation).

Automate this with @vue/preload-webpack-plugin or preload-webpack-plugin:

var PreloadWebpackPlugin = require('@vue/preload-webpack-plugin');

module.exports = {
  plugins: [
    new PreloadWebpackPlugin({
      rel: 'preload',
      include: 'initial'
    }),
    new PreloadWebpackPlugin({
      rel: 'prefetch',
      include: 'asyncChunks'
    })
  ]
};

Cache Busting with Content Hashes

Use [contenthash] in filenames so browsers cache aggressively but bust the cache when content changes:

module.exports = {
  output: {
    filename: '[name].[contenthash:8].js',
    chunkFilename: '[name].[contenthash:8].chunk.js'
  }
};

Set far-future cache headers on your CDN:

location /static/ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

The immutable directive tells browsers not to revalidate — the content hash guarantees the file never changes.

CDN Asset Serving

Configure webpack to reference assets from your CDN:

module.exports = {
  output: {
    publicPath: 'https://cdn.example.com/assets/'
  }
};

Every asset reference in the output bundle points to the CDN. Combined with content hashing and immutable cache headers, this means assets are served from edge nodes worldwide with zero revalidation overhead.

Build Performance

Optimization time itself matters when builds take minutes.

Parallel builds: Terser runs in parallel by default. For Babel, use thread-loader:

module.exports = {
  module: {
    rules: [{
      test: /\.js$/,
      use: [
        { loader: 'thread-loader', options: { workers: 4 } },
        'babel-loader'
      ]
    }]
  }
};

Persistent caching: Webpack 5's filesystem cache avoids reprocessing unchanged modules:

module.exports = {
  cache: {
    type: 'filesystem',
    buildDependencies: {
      config: [__filename]
    }
  }
};

First build takes the full time. Subsequent builds with unchanged files complete in seconds.

Complete Working Example: 2.5MB to 380KB

Here is the full production configuration that takes a typical React application from 2.5MB down to 380KB (gzipped):

var path = require('path');
var webpack = require('webpack');
var TerserPlugin = require('terser-webpack-plugin');
var CssMinimizerPlugin = require('css-minimizer-webpack-plugin');
var CompressionPlugin = require('compression-webpack-plugin');
var BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;
var MiniCssExtractPlugin = require('mini-css-extract-plugin');
var PurgeCSSPlugin = require('purgecss-webpack-plugin');
var ImageMinimizerPlugin = require('image-minimizer-webpack-plugin');
var glob = require('glob-all');
var zlib = require('zlib');

module.exports = {
  mode: 'production',
  devtool: 'source-map',

  entry: {
    app: './src/index.js'
  },

  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash:8].js',
    chunkFilename: '[name].[contenthash:8].chunk.js',
    publicPath: '/static/',
    clean: true
  },

  cache: {
    type: 'filesystem',
    buildDependencies: {
      config: [__filename]
    }
  },

  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        terserOptions: {
          compress: {
            drop_console: true,
            drop_debugger: true,
            passes: 3,
            toplevel: true,
            dead_code: true,
            collapse_vars: true,
            reduce_vars: true
          },
          mangle: { toplevel: true },
          output: { comments: false, ascii_only: true }
        },
        parallel: true,
        extractComments: false
      }),
      new CssMinimizerPlugin({
        minimizerOptions: {
          preset: ['advanced', {
            discardComments: { removeAll: true }
          }]
        }
      }),
      new ImageMinimizerPlugin({
        minimizer: {
          implementation: ImageMinimizerPlugin.sharpMinify,
          options: {
            encodeOptions: {
              jpeg: { quality: 80 },
              webp: { quality: 80 },
              png: { compressionLevel: 9 }
            }
          }
        }
      })
    ],
    splitChunks: {
      chunks: 'all',
      maxInitialRequests: 25,
      minSize: 20000,
      cacheGroups: {
        react: {
          test: /[\\/]node_modules[\\/](react|react-dom|scheduler)[\\/]/,
          name: 'vendor.react',
          priority: 20
        },
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendor.common',
          priority: 10
        },
        common: {
          minChunks: 2,
          priority: 5,
          reuseExistingChunk: true
        }
      }
    },
    runtimeChunk: 'single'
  },

  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: [
          { loader: 'thread-loader', options: { workers: 4 } },
          {
            loader: 'babel-loader',
            options: {
              cacheDirectory: true,
              presets: [['@babel/preset-env', {
                useBuiltIns: 'usage',
                corejs: 3,
                targets: '> 1%, not dead'
              }]]
            }
          }
        ]
      },
      {
        test: /\.css$/,
        use: [MiniCssExtractPlugin.loader, 'css-loader']
      },
      {
        test: /\.(png|jpe?g|gif|svg|webp)$/,
        type: 'asset',
        parser: {
          dataUrlCondition: { maxSize: 8192 }
        }
      },
      {
        test: /\.(woff|woff2)$/,
        type: 'asset/resource'
      }
    ]
  },

  plugins: [
    new webpack.DefinePlugin({
      'process.env.NODE_ENV': JSON.stringify('production'),
      __DEV__: false
    }),
    new MiniCssExtractPlugin({
      filename: '[name].[contenthash:8].css'
    }),
    new PurgeCSSPlugin({
      paths: glob.sync([
        path.join(__dirname, 'src/**/*.html'),
        path.join(__dirname, 'src/**/*.js')
      ]),
      safelist: { standard: [/^modal/, /^tooltip/] }
    }),
    new CompressionPlugin({
      filename: '[path][base].gz',
      algorithm: 'gzip',
      test: /\.(js|css|html|svg)$/,
      threshold: 1024,
      minRatio: 0.8
    }),
    new CompressionPlugin({
      filename: '[path][base].br',
      algorithm: 'brotliCompress',
      test: /\.(js|css|html|svg)$/,
      compressionOptions: {
        params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 11 }
      },
      threshold: 1024,
      minRatio: 0.8
    }),
    new BundleAnalyzerPlugin({
      analyzerMode: 'static',
      reportFilename: 'bundle-report.html',
      openAnalyzer: false
    })
  ],

  performance: {
    maxEntrypointSize: 250000,
    maxAssetSize: 200000,
    hints: 'error'
  }
};

Before and After Measurements

Metric Before After Reduction
Total bundle (raw) 2,510 KB 620 KB 75%
Total bundle (gzip) 780 KB 195 KB 75%
Total bundle (Brotli) 680 KB 162 KB 76%
CSS (raw) 285 KB 18 KB 94%
Largest JS chunk (gzip) 780 KB 85 KB 89%
Initial load chunks 1 4 —
Image assets 430 KB 210 KB 51%
Lighthouse Performance 42 94 +52 pts
Time to Interactive (3G) 12.3s 3.1s 75%

The biggest wins come from PurgeCSS (94% CSS reduction), code splitting (spreading load across cached chunks), and Brotli compression (76% total reduction). Image optimization contributes meaningfully but is secondary to JavaScript and CSS optimization.

Common Issues and Troubleshooting

1. Tree shaking does not remove unused library code. Most npm packages ship CommonJS modules, not ES modules. Tree shaking only works on ES module syntax. Check if the library provides an ES module build (look for module or exports fields in its package.json). If not, import specific subpaths: require('lodash/debounce') instead of require('lodash').

2. PurgeCSS removes classes that are dynamically generated. If your code builds class names at runtime (e.g., 'btn-' + variant), PurgeCSS cannot detect them statically. Add them to the safelist using regex patterns: safelist: { standard: [/^btn-/] }. Audit your CSS output after enabling PurgeCSS — visual regressions are the most common issue.

3. Code splitting produces too many small chunks. If your network waterfall shows dozens of tiny requests, increase minSize in splitChunks or reduce maxInitialRequests. HTTP/2 multiplexing helps, but each request still has overhead. Aim for chunks between 20KB and 150KB gzipped.

4. Content hash changes when only comments or whitespace change. Terser's output is not deterministic if options differ between builds. Pin your Terser version, use extractComments: false, and ensure cache.type: 'filesystem' is enabled. Also check that your runtimeChunk: 'single' is set — without it, the runtime code embedded in each chunk causes hash changes when any chunk changes.

5. Source maps expose proprietary code in production. Use devtool: 'hidden-source-map' instead of 'source-map'. This generates source maps but does not add the //# sourceMappingURL comment to the bundle. Upload the source maps to your error tracking service (Sentry, Datadog) and keep them off your public server.

Best Practices

  1. Measure before optimizing. Run webpack-bundle-analyzer and identify the largest modules before changing configuration. Optimizing a 5KB module is pointless when a 400KB dependency sits untouched.

  2. Set performance budgets and enforce them in CI. Use performance.hints: 'error' in webpack and add bundle size checks to your CI pipeline. Budgets prevent regressions from landing.

  3. Split vendor and application code. Vendor code changes infrequently. Separating it into its own chunk means returning users load only the application delta, not the entire dependency tree.

  4. Prefer Brotli over gzip for static assets. Brotli produces consistently smaller files and is supported by all modern browsers. Fall back to gzip for legacy clients.

  5. Audit dependencies ruthlessly. Run npx depcheck to find unused dependencies. Use bundlephobia.com to check the install and bundle size of packages before adding them. A single careless npm install can add hundreds of kilobytes.

  6. Use dynamic imports for anything below the fold. Charts, modals, rich text editors, admin panels — if the user does not need it on first paint, lazy load it. The perceived performance improvement is dramatic.

  7. Enable filesystem caching in development and CI. Webpack 5's persistent cache cuts rebuild times from minutes to seconds. There is no reason not to use it.

  8. Test on real devices and real networks. Chrome DevTools throttling is an approximation. Test on an actual mid-range Android phone over a real 3G connection. The results will motivate your optimization work like nothing else.

References

Quick Links
Back to LibraryBlog ArticlesHomepage
Need Expert Help?

We build AI applications, APIs, and enterprise solutions.

Request Consultation
Powered by Contentful