Skip to content
Velloreth
Web Development 4 min read

JavaScript Bundlers Explained: What They Actually Do

A bundler resolves imports, transforms code and writes a file the browser can load. Learn the graph, the loaders, and the output.

By

The job

A bundler does four things:

  1. Builds a dependency graph
  2. Transforms each file
  3. Optimises the result
  4. Writes the output

The graph

It starts at an entry point.

// src/index.js
import { render } from './app.js';
import './styles.css';

It follows every import, and the result is a graph of modules.

A dynamic import is a separate node, and it becomes a chunk.

const mod = await import('./heavy.js');

The transformation

A loader transforms a file the bundler cannot read.

FileLoader
.tsa TypeScript loader
.cssa CSS loader
.svgan SVG loader
.jsxa JSX transform

A plugin hooks into the build lifecycle.

A loader is per file, and a plugin is per build.

The optimisation

Minification removes whitespace and shortens a name.

Tree shaking removes code that is never used.

Dead code elimination removes a branch that is never taken.

Scope hoisting merges the modules into one scope.

Compression is usually left to the server, with gzip or brotli.

Tree shaking

It works when the module is ESM and the bundler can prove the export is unused.

// utils.js
export function used() {}
export function unused() {}   // removed

A side effect prevents the removal.

// A side effect: the import has an effect even if nothing is used
import './polyfill.js';

A package declares sideEffects: false to say that its modules are safe to remove.

The output

One or more chunks.

dist/
  index.a1b2c3.js      # the entry
  vendor.d4e5f6.js     # a shared dependency
  heavy.g7h8i9.js      # a lazy chunk
  index.j0k1l2.css

A content hash in the name changes only when the content changes, which makes the browser cache work.

A chunk is loaded on demand with a dynamic import.

The dev server

It serves from memory and reloads on a change.

Hot module replacement updates a module without a full reload.

The dev build is not optimised, because the speed of the rebuild matters more.

A production build is optimised, and it is the one that is measured.

The tools

ToolNotes
Vitenative ESM in dev, Rollup in prod
webpackthe most configurable
Rollupa library-friendly output
esbuildvery fast, a Go binary
Parcelzero config
Turbopacka Rust-based successor

Vite is the common default for a new project.

esbuild is often used as the transformer inside another tool.

The source map

A file that maps the output back to the source.

//# sourceMappingURL=index.a1b2c3.js.map

It makes a stack trace readable.

It should not be served publicly unless the source is public, because it exposes the original code.

Do you need one

For a small site, a native ESM import may be enough.

<script type="module" src="/app.js"></script>

For a large application, a bundler is still needed for the resolution, the transformation, the minification and the splitting.

A build tool such as Vite uses a bundler for production and native ESM in development, which is the best of both.

Common mistakes

No content hash. A stale cache.

A source map served publicly. The source is exposed.

A large vendor chunk. A slow first load.

No code splitting. One large file.

A side effect that blocks tree shaking. A larger bundle.

A dev build measured. The wrong number.

A minifier that breaks a name. A runtime error.

No compression. A larger transfer.

A polyfill for a modern browser. Unnecessary code.

No bundle analysis. The size is a mystery.

A quotable summary

A JavaScript bundler starts at an entry point, follows every import to build a dependency graph, transforms each file with a loader, optimises the result with minification and tree shaking, and writes one or more chunks the browser can load. A loader is per file and a plugin is per build, a content hash makes the browser cache work, and a dynamic import becomes a chunk that is loaded on demand. A small site may not need a bundler, and a large application still does.

For the related topics, see code-splitting-guide and javascript-modules-guide. For the broader context, javascript-performance-tips and esm-vs-commonjs.

Frequently asked questions

What does a JavaScript bundler do?
It starts at an entry point, follows every import to build a dependency graph, transforms each file with a loader, and writes one or more output files that the browser can load. It also handles a non-JavaScript asset such as CSS or an image, and it can split the output into chunks.
What is the difference between a loader and a plugin?
A loader transforms a single file, such as a TypeScript file into JavaScript. A plugin hooks into the build lifecycle and can do anything, such as generate an HTML file, copy an asset, or define a global constant. A loader is per file and a plugin is per build.
What is tree shaking?
The removal of code that is never used, based on the static import graph. It works when the module is ESM and the bundler can prove the export is unused. A side effect in a module prevents the removal, which is why a package declares sideEffects.
What is a chunk?
An output file. A bundler can produce several chunks, such as one per route or one per shared dependency, so the browser downloads only what a page needs. A chunk is loaded on demand with a dynamic import.
What is a source map?
A file that maps the bundled output back to the original source, so a stack trace and a debugger point at the real file. It is generated in development and often in production, and it should not be served publicly unless the source is public.
Do I need a bundler in 2026?
For a small site, a native ESM import may be enough. For a large application, a bundler is still needed for the dependency resolution, the transformation, the minification and the code splitting. A build tool such as Vite uses a bundler for production and native ESM in development.