Understanding your bundleWhat is bundle?A single JavaScript file (or set of files) that a build tool creates by combining all your source code and its imports together. Ask AI for more

Before optimizing, you need to see what is in your bundle. Vite and webpack both have visualization tools that show you exactly which libraries and files are contributing to the total size.

# Vite - generates a visual treemap of your bundle
npx vite build
npx vite-bundle-visualizer

# Webpack - similar visualization
npx webpack-bundle-analyzer dist/stats.json

The first time you run a bundle analyzerWhat is bundle analyzer?A tool that visualizes the size and composition of your JavaScript bundle to identify what to optimize. Ask AI for more, you will almost certainly find surprises. A library you imported once for a single function might be contributing 100KB. A barrel import (import { x } from './utils') might be pulling in 50 files when you need 1.

The cost of JavaScript vs other assets

To understand why bundleWhat is bundle?A single JavaScript file (or set of files) that a build tool creates by combining all your source code and its imports together. Ask AI for more optimization matters more than optimizing other asset types, consider how the browser processes each one:

JavaScript is the only asset that blocks the main thread during every processing stage. A 200KB JS file costs 5-10x more in time-to-interactive than a 200KB image.

Tree shakingWhat is tree shaking?A build tool feature that removes unused exported code from your final bundle, reducing the amount of JavaScript shipped to users. Ask AI for more

Tree shaking is the process of removing unused code from your final bundleWhat is bundle?A single JavaScript file (or set of files) that a build tool creates by combining all your source code and its imports together. Ask AI for more. Modern bundlers (Vite, webpack, Rollup) do this automatically, but only when your code uses ES moduleWhat is es modules?The official JavaScript module standard using import and export - enabled in Node.js via "type": "module" in package.json. Ask AI for more syntax.

// Tree-shakeable: bundler can see you only use 'debounce'
import { debounce } from './utils';

// NOT tree-shakeable: bundler can't analyze dynamic access
const utils = require('./utils');
const debounce = utils.debounce;

Barrel fileWhat is barrel file?An index.js that re-exports from multiple modules in one place so consumers can import everything from a single path - can hurt tree shaking if overused. Ask AI for more problem

Barrel files (an index.ts that re-exports everything from a directory) can defeat tree shaking:

// utils/index.ts - barrel file
export { formatDate } from './date';
export { formatCurrency } from './currency';
export { parseCSV } from './csv';        // 50KB dependency
export { renderChart } from './chart';    // 200KB dependency

// Your code - you only need formatDate
import { formatDate } from './utils';
// But depending on the bundler, you might get ALL of the above

The fix is to import directly from the source file:

// Direct import - guaranteed to only include what you need
import { formatDate } from './utils/date';

Replacing heavy libraries

One of the highest-leverage optimizations is replacing heavy libraries with lighter alternatives that do the same thing. AI tools default to the most popular library, which is often not the lightest.

// What AI generates - 67KB for one date format
import moment from 'moment';
const formatted = moment(date).format('YYYY-MM-DD');

// What you should use - 2KB
import { format } from 'date-fns';
const formatted = format(date, 'yyyy-MM-dd');

// Even better - 0KB, built into the platform
const formatted = date.toISOString().split('T')[0];

Dynamic imports for heavy features

Not every feature needs to be in the initial bundleWhat is bundle?A single JavaScript file (or set of files) that a build tool creates by combining all your source code and its imports together. Ask AI for more. If a feature is only used by some users or only appears after an interaction, load it dynamically:

// Bad: PDF library (500KB) loaded for every user
import { PDFDocument } from 'pdf-lib';

// Good: loaded only when user clicks "Export PDF"
async function exportPDF(data) {
  const { PDFDocument } = await import('pdf-lib');
  const doc = await PDFDocument.create();
  // ... generate PDF
}

This pattern works for any heavy feature: rich text editors, chart libraries, image processing, CSV parsing, or anything that only a subset of users will trigger.

Decision table: when to dynamically import

Analyzing import cost

Before adding any dependencyWhat is dependency?A piece of code written by someone else that your project needs to work. Think of it as a building block you import instead of writing yourself. Ask AI for more, check its cost:

# Check bundle size impact of a package
npx bundlephobia <package-name>

# Or use the website: https://bundlephobia.com

Code splittingWhat is code splitting?Breaking your application into smaller JavaScript chunks that load on demand so users only download the code needed for the page they're viewing. Ask AI for more strategies

There are three main strategies for splitting your bundleWhat is bundle?A single JavaScript file (or set of files) that a build tool creates by combining all your source code and its imports together. Ask AI for more:

Route-based splitting

Each page gets its own chunk. This is the highest-impact, lowest-effort strategy:

// Each route is a separate chunk - users only download
// the code for the page they are visiting
const Home = lazy(() => import('./pages/Home'));
const About = lazy(() => import('./pages/About'));
const Dashboard = lazy(() => import('./pages/Dashboard'));

Component-based splitting

Heavy components that are not visible on initial load get their own chunks:

// Modal content, charts, editors - anything below the fold
// or behind a user action
const RichTextEditor = lazy(() => import('./RichTextEditor'));
const ChartDashboard = lazy(() => import('./ChartDashboard'));

Library-based splitting

Configure your bundler to put large third-party libraries in separate chunks:

// vite.config.js
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'react-vendor': ['react', 'react-dom'],
          'chart': ['chart.js'],
        }
      }
    }
  }
});

Practical workflow

Here is the workflow for optimizing a bundleWhat is bundle?A single JavaScript file (or set of files) that a build tool creates by combining all your source code and its imports together. Ask AI for more:

1. Measure: Run bundle analyzerWhat is bundle analyzer?A tool that visualizes the size and composition of your JavaScript bundle to identify what to optimize. Ask AI for more to see current state
2. Identify: Find the largest contributors
3. Replace: Swap heavy libraries for lighter alternatives or native APIs
4. Split: Move heavy features behind dynamic imports
5. Verify: Run bundle analyzer again to confirm improvement
6. Budget: Set a bundle size limit in your CI to prevent regression