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 Velloreth
The job
A bundler does four things:
- Builds a dependency graph
- Transforms each file
- Optimises the result
- 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.
| File | Loader |
|---|---|
.ts | a TypeScript loader |
.css | a CSS loader |
.svg | an SVG loader |
.jsx | a 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
| Tool | Notes |
|---|---|
| Vite | native ESM in dev, Rollup in prod |
| webpack | the most configurable |
| Rollup | a library-friendly output |
| esbuild | very fast, a Go binary |
| Parcel | zero config |
| Turbopack | a 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.
Related reading
For the related topics, see code-splitting-guide and javascript-modules-guide. For the broader context, javascript-performance-tips and esm-vs-commonjs.