Back to Guides

JavaScript Bundle Size Optimization

Reduce JavaScript bundle sizes and improve page load times with code splitting, tree shaking, dynamic imports, and bundle analysis techniques.

Why JavaScript Bundle Size Matters

JavaScript is the most expensive resource on the web. Unlike images, JavaScript must be downloaded, parsed, compiled, and executed. Large bundles directly impact Time to Interactive (TTI) and Total Blocking Time (TBT).

Performance Impact

  • Network cost: Every KB takes time to download on slow connections
  • Parse/compile cost: JavaScript must be parsed before execution (slower on mobile)
  • Execution cost: Running JavaScript blocks the main thread
  • Memory cost: Large bundles consume more memory, especially on low-end devices

Benchmark: On a mid-range mobile device, parsing and compiling 1MB of JavaScript can take 2-3 seconds, blocking user interaction during that time.

Step 1: Analyze Your Bundle

Before optimizing, understand what's in your bundle. Use bundle analyzers to visualize dependencies and identify optimization opportunities.

Webpack Bundle Analyzer

bash
# Install webpack-bundle-analyzer
npm install --save-dev webpack-bundle-analyzer


# Or with yarn
yarn add -D webpack-bundle-analyzer
javascript
// webpack.config.js
const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;


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

Next.js Bundle Analysis

bash
# Install @next/bundle-analyzer
npm install --save-dev @next/bundle-analyzer
javascript
// next.config.js
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
});


module.exports = withBundleAnalyzer({
  // Your Next.js config
});


// Run with: ANALYZE=true npm run build

Code Splitting Strategies

Split your JavaScript into smaller chunks that load only when needed. This reduces initial bundle size and improves Time to Interactive.

1. Dynamic Imports

javascript
// Bad: Import everything upfront
import Chart from 'chart.js';
import DatePicker from 'react-datepicker';


// Good: Import only when needed
function Dashboard() {
  const [showChart, setShowChart] = useState(false);


  const loadChart = async () => {
    const Chart = await import('chart.js');
    // Use Chart
  };


  return <button onClick={loadChart}>Show Chart</button>;
}

2. React Lazy Loading

javascript
// Lazy load React components
import { lazy, Suspense } from 'react';


const HeavyComponent = lazy(() => import('./HeavyComponent'));


function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <HeavyComponent />
    </Suspense>
  );
}


// Load multiple components
const [AdminPanel, Analytics] = [
  lazy(() => import('./AdminPanel')),
  lazy(() => import('./Analytics'))
];

3. Route-Based Code Splitting

javascript
// Next.js automatic route-based splitting
// Each page is automatically code-split


// pages/index.js
export default function Home() {
  return <h1>Home</h1>;
}


// pages/about.js - separate bundle
export default function About() {
  return <h1>About</h1>;
}


// React Router with lazy loading
import { lazy } from 'react';
import { BrowserRouter, Routes, Route } from 'react-router-dom';


const Home = lazy(() => import('./pages/Home'));
const About = lazy(() => import('./pages/About'));
const Dashboard = lazy(() => import('./pages/Dashboard'));


function App() {
  return (
    <BrowserRouter>
      <Suspense fallback={<LoadingSpinner />}>
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/about" element={<About />} />
          <Route path="/dashboard" element={<Dashboard />} />
        </Routes>
      </Suspense>
    </BrowserRouter>
  );
}

Tree Shaking & Dead Code Elimination

Tree shaking removes unused code from your bundle. Use ES6 modules and import only what you need.

Import Specific Functions

javascript
// Bad: Import entire library (100+ KB)
import _ from 'lodash';
const result = _.debounce(fn, 300);


// Good: Import specific function (5 KB)
import debounce from 'lodash/debounce';
const result = debounce(fn, 300);


// Bad: Import all icons
import * as Icons from 'react-icons/fa';


// Good: Import specific icons
import { FaHome, FaUser } from 'react-icons/fa';


// Bad: Import entire date library
import moment from 'moment'; // 67 KB


// Good: Use lightweight alternative
import dayjs from 'dayjs'; // 2 KB

Configure Tree Shaking

javascript
// package.json - Mark as side-effect free
{
  "name": "your-package",
  "sideEffects": false,
  // Or specify files with side effects
  "sideEffects": ["*.css", "*.scss"]
}


// webpack.config.js
module.exports = {
  mode: 'production', // Enables tree shaking
  optimization: {
    usedExports: true,
    minimize: true
  }
};

Lightweight Library Alternatives

Replace heavy libraries with lighter alternatives or native browser APIs when possible.

Popular Library Alternatives

Heavy LibrarySizeLightweight AlternativeSize
Moment.js67 KBday.js / date-fns2-7 KB
Lodash (full)71 KBlodash-es (per-method)1-5 KB
Axios13 KBfetch (native) / ky0-4 KB
jQuery87 KBNative DOM APIs0 KB

Use Native Browser APIs

javascript
// Instead of Axios
const response = await fetch('/api/data');
const data = await response.json();


// Instead of jQuery DOM manipulation
document.querySelector('.btn').addEventListener('click', handleClick);


// Instead of Lodash debounce (simple version)
function debounce(fn, delay) {
  let timeout;
  return (...args) => {
    clearTimeout(timeout);
    timeout = setTimeout(() => fn(...args), delay);
  };
}


// Instead of Moment.js for simple formatting
const formatter = new Intl.DateTimeFormat('en-US', {
  year: 'numeric',
  month: 'long',
  day: 'numeric'
});
console.log(formatter.format(new Date()));

Production Build Optimizations

1. Minification & Compression

javascript
// webpack.config.js
const TerserPlugin = require('terser-webpack-plugin');


module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        terserOptions: {
          compress: {
            drop_console: true, // Remove console.log
            dead_code: true,
            unused: true
          },
          mangle: true // Shorten variable names
        }
      })
    ]
  }
};

2. Environment-Specific Code

javascript
// Remove development-only code in production
if (process.env.NODE_ENV === 'development') {
  // Debug logging (removed in production build)
  console.log('Debug info:', data);
}


// Webpack DefinePlugin
const webpack = require('webpack');


module.exports = {
  plugins: [
    new webpack.DefinePlugin({
      'process.env.NODE_ENV': JSON.stringify('production')
    })
  ]
};

3. Vendor Splitting

javascript
// webpack.config.js - Separate vendor bundles
module.exports = {
  optimization: {
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendors',
          priority: 10
        },
        common: {
          minChunks: 2,
          priority: 5,
          reuseExistingChunk: true
        }
      }
    }
  }
};

Set Performance Budgets

Establish and enforce JavaScript bundle size limits to prevent performance regressions.

Recommended Bundle Sizes

  • Initial JavaScript: < 200 KB (gzipped)
  • Total JavaScript: < 500 KB (gzipped)
  • Per-route chunks: < 50 KB (gzipped)
  • Third-party libraries: < 100 KB (gzipped)

Enforce with Bundlesize

bash
# Install bundlesize
npm install --save-dev bundlesize
javascript
// package.json
{
  "bundlesize": [
    {
      "path": "./dist/main.*.js",
      "maxSize": "200 KB"
    },
    {
      "path": "./dist/vendor.*.js",
      "maxSize": "100 KB"
    }
  ],
  "scripts": {
    "test:size": "bundlesize"
  }
}

Monitor Bundle Size Over Time

Run bundle analysis on every build
Add bundlesize checks to CI/CD pipeline
Review dependency updates for size impact
Track bundle size metrics in analytics
Use tools like bundlephobia.com before adding dependencies

Analyze Your JavaScript Performance

Get AI-powered recommendations for reducing your JavaScript bundle size and improving page load performance.

Test Your Website