How Frontend Bundling Works

1. Why Bundlers Exist

In 2010, browsers didn't support modules natively. JavaScript had no official way to split code into files and import them. Developers worked around this with globals, IIFEs, or script tags — all fragile and unscalable.

The Three Problems Bundlers Solve

2. The Bundling Pipeline

Every bundler follows the same fundamental pipeline, regardless of tool. The steps are always: find → read → parse → transform → link → optimize → emit.

Step-by-Step Breakdown

1. 1
   Entry Point — You tell the bundler where to start (src/main.ts, src/index.jsx). Everything else is discovered from here.
2. 2
   Resolve — When the bundler sees import React from 'react', it must figure out what file that maps to. It checks node_modules/react, reads package.json exports field, follows the resolution algorithm. This produces an absolute file path.
3. 3
   Load — Read the file from disk. This is also where plugins intercept to handle non-JS files (CSS, images, WASM). A CSS loader transforms import './styles.css' into JavaScript that injects a <style> tag at runtime.
4. 4
   Parse → AST — The source string is parsed into an Abstract Syntax Tree (AST) — a tree data structure representing every token in the code. Import statements, function calls, variable declarations are all nodes in this tree. The bundler needs the AST to understand the code structurally.
5. 5
   Transform — Plugins walk the AST and modify it. TypeScript types are stripped, JSX is converted to React.createElement() calls, modern syntax is downgraded to ES5. The AST is then serialized back to a JS string.
6. 6
   Dependency Discovery + Link — After parsing each module, the bundler extracts its imports and adds them to a work queue. This process repeats recursively until every module in the graph has been processed. The result is a complete module graph.
7. 7
   Tree Shaking — Walk the module graph and mark which exports are actually used. Anything unreachable from the entry point gets flagged as dead code and removed from the output.
8. 8
   Chunking — Decide which modules go in which output file. Typically: one main chunk, one vendor chunk (node_modules), and async chunks for lazy-loaded routes.
9. 9
   Minification — Rename variables to single letters, remove whitespace and comments, collapse constant expressions. Makes files 60–80% smaller.
10. 10
    Emit — Write output files to disk: dist/main.js, dist/vendor.js, dist/chunk-123.js. Also generates index.html with correct <script> tags injected.

3. Module Systems

Bundlers must handle several different module formats — code you write, code from npm packages, and code targeting different environments.

Why ESM Is the Only Tree-Shakeable Format

The key difference: ESM imports and exports are static — they appear at the top level of a file and cannot change at runtime. The bundler can read the file and know exactly what is exported and imported before running any code.

// bundler sees this at parse time
import { format } from 'date-fns'

export function greet(name) {
  return `Hello ${name}`
}

// bundler knows: only 'format' is used,
// and 'greet' is exported

// bundler cannot know what this imports
const utils = require(someVar)

// or conditionally:
if (process.env.NODE_ENV === 'test') {
  module.exports = require('./mock')
} else {
  module.exports = require('./real')
}

4. The Dependency Graph

A bundler builds a directed graph where each node is a module and each edge is an import relationship. This graph is everything — it drives tree shaking, chunking, and output generation.

How the Graph Is Built (Algorithm)

1. 1
   Start with the entry file. Add it to a queue and a visited set.
2. 2
   Dequeue a module. Read and parse it. Extract all import statements.
3. 3
   For each import: resolve the path to an absolute file path. If not already in the visited set, add it to the queue.
4. 4
   Repeat until the queue is empty. Every reachable module has been processed exactly once.

Circular Dependencies

Module A imports B, and B imports A. Both ESM and CJS handle this differently, but bundlers must detect and handle cycles to avoid infinite loops during graph construction. ESM allows cycles (exports may be temporarily undefined at first), CJS may produce partially initialized objects.

5. Transforms & Loaders

Bundlers speak JavaScript natively. Everything else — TypeScript, JSX, CSS, images, WASM — requires a transform (Rollup / Vite call them plugins; webpack calls them loaders).

The Transform Pipeline per Module

Common Transforms

The AST — Why It Matters

Transforms don't do string replacement. They parse source into an AST, modify the tree, then print it back to a string. This is why transforms are correct — they understand code structure, not just text patterns.

6. Tree Shaking

Tree shaking is the process of eliminating dead code — exports that exist in source but are never imported by anything reachable from the entry point. The name comes from shaking a tree and watching dead leaves fall.

How It Works

The Mark-and-Sweep Algorithm

1. 1
   Mark entry exports as "live" — everything the entry point uses is marked.
2. 2
   Propagate liveness — if a live function calls other functions or imports from other modules, those are also marked live.
3. 3
   Sweep — anything not marked live is excluded from the output.

What Breaks Tree Shaking

Scope Hoisting (Module Inlining)

A related optimization: instead of wrapping each module in a function closure (the old approach), Rollup and modern webpack flatten the module graph into a single scope. This makes the code smaller and faster — no function call overhead per module, and variable names can be further shortened by minification.

7. Code Splitting

Without code splitting, your entire app ships as one big JS file. The user must download ALL the code before anything runs — even code for pages they'll never visit.

Code splitting breaks the bundle into multiple files loaded on demand. The initial load only fetches what's needed to render the first screen.

Types of Code Splitting

A — Static Splitting (Multiple Entry Points)

// vite.config.ts / webpack.config.js
{
  build: {
    rollupOptions: {
      input: {
        main: 'src/main.ts',
        admin: 'src/admin/main.ts'   // separate entry → separate bundle
      }
    }
  }
}

Two entry points = two separate bundles. Used for multi-page apps where each page is completely independent.

B — Dynamic Splitting (Lazy Imports)

// React lazy route example
const HomePage = React.lazy(() => import('./pages/Home'))
const AboutPage = React.lazy(() => import('./pages/About'))

// When user navigates to /about, the browser fetches
// chunk-About-abc123.js on demand — not at initial load

C — Vendor Splitting

Separate your app code from npm dependencies. Libraries like React, lodash, and moment rarely change. Splitting them out means users cache vendor.js across deployments — they only re-download app.js when your code changes.

// vite.config.ts
{
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom', 'react-router-dom'],
          ui:     ['@radix-ui/react-dialog', '@radix-ui/react-dropdown-menu'],
        }
      }
    }
  }
}

8. Chunk Strategy

The bundler decides which modules go in which output file. This decision affects both initial load performance and how effectively the browser cache is used across deployments.

Content Hashing

Output filenames include a hash of the file contents: main.abc123.js. If the file doesn't change, the hash doesn't change. The browser's cache stays valid indefinitely. Only changed files get new hashes — and therefore new cache keys.

Shared Chunks

When module A and module B both import Button.tsx, the bundler doesn't duplicate it. Instead it extracts Button.tsx into a shared chunk that both lazy chunks depend on.

Prefetching & Preloading Chunks

The bundler can emit hints to the browser to prefetch chunks the user will likely need next, before they navigate there:

<!-- Generated by bundler in index.html -->
<link rel="prefetch" href="/chunk-About.abc123.js" />
<!-- Browser downloads this in background when idle -->
<!-- When user clicks "About", it's already in cache -->

9. Minification & Optimization

Minification reduces file size without changing behavior. It's applied after all other transforms in production builds.

What Minifiers Do

Minifier Comparison

Gzip & Brotli (Server-side Compression)

After minification, the server compresses files before sending them. Minified JS + Brotli compression typically achieves 75–85% size reduction vs the original source.

10. Source Maps

After minification, your code looks like function a(b,c){return b+c}. When an error occurs in production, the stack trace points to this minified line — completely useless for debugging.

Source maps are separate files (main.js.map) that tell browser DevTools how to map minified code back to your original source, including file name and line number.

How Source Maps Work

Source Map Types

11. Hot Module Replacement (HMR)

HMR is the dev server feature that updates your browser in real time when you save a file — without a full page reload. React component state is preserved, scroll position stays, only the changed module is swapped.

How HMR Works

1. 1
   You save a file. The bundler detects the change via file system watcher (chokidar, fs.watch).
2. 2
   The bundler re-processes only the changed module and its dependents (not the entire graph). This is the "hot path" — it's why Vite is so fast in dev: it recompiles one file, not everything.
3. 3
   The dev server sends a WebSocket message to the browser: "Module X has a new version."
4. 4
   The browser's HMR runtime receives the message, fetches the new module code, and runs the module's hot.accept() handler.
5. 5
   The hot.accept() handler (provided by React Fast Refresh, Vue HMR, etc.) swaps the component in place without losing app state.

Vite vs webpack HMR Speed

12. Asset Handling

Everything that isn't JavaScript goes through asset handling: CSS, images, fonts, JSON, SVGs, WASM.

CSS Handling

When you import './styles.css' in JavaScript, the bundler needs to handle it. Two main strategies:

CSS Modules

CSS Modules scope class names locally by hashing them. .button in Button.module.css becomes .button_abc123 — impossible to conflict with any other component's styles.

/* Button.module.css */
.button { background: blue; }

/* Button.tsx */
import styles from './Button.module.css'
<button className={styles.button}>Click me</button>

/* Output HTML */
<button class="button_3kf9a">Click me</button>

Image & Font Assets

The bundler processes asset files based on size thresholds:

• Small files (<4KB) — inlined as base64 data URIs. Zero extra HTTP requests.
• Large files (>4KB) — copied to output directory with content-hashed filename. Referenced by URL string in JS/CSS.

// vite.config.ts
{
  build: {
    assetsInlineLimit: 4096   // files smaller than 4KB → base64 inline
  }
}

13. Bundler Comparison

When to Use What

14. Dev Mode vs Production Mode

The bundler behaves very differently depending on the mode. Dev prioritizes speed and debuggability; production prioritizes output size and runtime performance.

Mental Model — The Complete Picture

Quick Cheat Sheet

References

• 1
  webpack Concepts — Official Docs

  Entry, output, loaders, plugins, mode, and browser compatibility. The canonical bundler concepts guide.
• 2
  Why Vite — Vite Official Docs

  Explains the motivation behind Vite's architecture: native ESM in dev, Rollup in prod, and why webpack is slow.
• 3
  Rollup Introduction — Official Docs

  How Rollup's tree shaking and scope hoisting work. Best source for understanding module-level optimizations.
• 4
  esbuild API — Official Docs

  esbuild's transform and build APIs. Explains its architecture and why it's 10–100x faster than JS-based tools.
• 5
  MDN: Tree Shaking

  Clear explanation of tree shaking concept with ESM vs CJS context.
• 6
  webpack: Code Splitting Guide

  Entry points, dynamic imports, and SplitChunksPlugin. The most complete guide to chunking strategies.
• 7
  SurviveJS: Source Maps Deep Dive

  Comprehensive comparison of all source map types, their trade-offs, and production recommendations.
• 8
  Vite: HMR Guide

  How Vite's HMR works, the HMR API, and how React Fast Refresh integrates with it.
• 9
  Chrome DevTools: Source Maps

  How Chrome DevTools uses source maps for debugging. Covers loading, mapping, and security considerations.
• 10
  web.dev: How CommonJS is making your bundles larger

  Detailed article on why CJS breaks tree shaking with concrete examples and size comparisons.