Bundlers & build tools

What a bundler does

A real JavaScript app is almost never one file. It is split into many small files called modules. A module uses code from other modules with import. An app may import:

• your own components and helper files;
• CSS files and images;
• packages you installed with npm;
• code that should load only after a user clicks something.

A bundler is a tool that reads all those imports before you put the site online. Then it writes a few files that the browser can download quickly.

Many tools do this job, such as Vite, webpack, Rollup, esbuild, Turbopack, and Rspack. Most of them also do more: they run your app while you work on it, accept plugins, make the code smaller, and write source maps for debugging. This lesson explains each of these.

This lesson builds on these lessons: why modules exist, import and export, module resolution, and npm and package.json. It also links to dynamic import and CommonJS vs ESM.

Browsers can load modules on their own. Modules loaded this way are called native ES modules. They work well. But a big app still runs into problems.

The first problem is a chain of downloads. The browser downloads main.js. Only then does it see what main.js imports, so it downloads those files next. Then it sees their imports, and so on. A step-by-step chain like this is called a waterfall.

const files = ["main.js", "cart.js", "price.js"];
console.log(files.join(" -> "));

Line 1 lists three files. Line 2 joins them with arrows and prints main.js -> cart.js -> price.js. Read it as: main.js imports cart.js, and cart.js imports price.js.

Three files are not always three slow downloads. The browser can keep files it downloaded before; this is called caching. It can also download several files at the same time once it knows about them. So bundling is a trade-off. The goal is not simply the fewest files.

The second problem is package names. You import an npm package by its name, like lodash-es. A name with no ./ and no web address is called a bare specifier. The browser can't download a bare name on its own. It needs a web address.

The table below lists the main reasons teams bundle. Each row names a problem, then says what the bundler does about it.

A bundler can also change files before the browser sees them. These changes are called transforms:

• TypeScript becomes plain JavaScript.
• JSX, the HTML-like code used in React, becomes plain function calls.
• An import of a CSS file becomes a real CSS file.
• An import of an image becomes the image's web address.

After that, the bundler can make the code smaller, remove code nobody uses, and move code that can wait into its own file. It can also add a short code to each file name, so the browser can keep files that didn't change for months. You'll see each of these later in this lesson.

A small site can skip the bundler and use an import map instead. An import map is a list that tells the browser which web address to use for each package name.

1<script type="importmap">2{3  "imports": {4    "lodash-es": "https://cdn.example/lodash-es/index.js"5  }6}7</script>8<script type="module">9  import { chunk } from "lodash-es";10  console.log(chunk([1, 2, 3, 4], 2));11</script>

In plain words, line by line:

1. Line 1 starts the import map.
2. Line 4 says: when code imports lodash-es, download it from this web address.
3. Line 8 starts a module script.
4. Line 9 imports chunk by its package name. This works only because of the import map.
5. Line 10 splits [1, 2, 3, 4] into groups of 2 and prints [[1, 2], [3, 4]].

The entry is the first file the bundler reads. Each import in it points to another file. Those files can import more files. Together, the files and their imports form a module graph: a map of which file imports which.

It is a graph, not a simple list, because two files can import the same file.

const imports = { cart: ["price"], checkout: ["price"] };
const files = new Set(["cart", "checkout", ...imports.cart, ...imports.checkout]);
console.log([...files].join(", "));

Line 1 says that cart imports price, and checkout imports price too. Line 2 puts all the names in a Set. A Set keeps only one copy of each value, so price appears once. Line 3 prints cart, checkout, price.

A real bundler might put a shared file like price into its own chunk, which both pages load. Or it might copy a very small shared file into each chunk that needs it.

The bundler must also choose an order. A file can only run after the files it imports. So each file goes after the files it imports. Files can also import each other in a loop, called a cycle. Real bundlers handle cycles, but this lesson's example has none.

The replay below steps through that ordering. In the lesson's real bundler, a tool called acorn first reads the four files and finds their imports. The replay starts after that, so you can watch just the ordering.

1const imports = new Map([Run2  ["/src/main.js", ["/src/setup.js", "/src/math.js", "/src/format.js"]],3  ["/src/format.js", ["/src/math.js"]],4  ["/src/math.js", []],5  ["/src/setup.js", []],6]);7 8const seen = new Set();9const order = [];10function visit(id) {11  if (seen.has(id)) return;12  seen.add(id);13  for (const dependency of imports.get(id)) visit(dependency);14  order.push(id);15}16 17visit("/src/main.js");18console.log(order.join(" -> "));

Here is a real bundler that works, in a few dozen lines. It keeps four small files in memory:

• main.js, the entry;
• setup.js, which only logs a message;
• math.js, which exports version, add, and multiply;
• format.js, which exports label and loud.

The bundler does five jobs, in this order:

1. It reads each file with acorn. acorn is a library that turns JavaScript text into a tree of objects, one object for each piece of code. This tree is called an AST (abstract syntax tree).
2. It finds each file's imports and exports in that tree.
3. It puts the files in order, so each file comes after the files it imports.
4. It replaces each import with a call to a small function called require.
5. It writes everything into one file that runs.

1import { parse } from "acorn";2 3function importsOf(id, source) {4  const ast = parse(source, { ecmaVersion: "latest", sourceType: "module" });5  return ast.body6    .filter((node) => node.type === "ImportDeclaration")7    .map((node) => resolveSpecifier(id, node.source.value));8}9 10function visit(id) {11  if (seen.has(id)) return;12  seen.add(id);13  for (const dependency of importsOf(id, files[id])) visit(dependency);14  order.push(id);15}

In plain words, line by line:

1. Line 1 loads the parse function from acorn.
2. Line 4 reads one file. sourceType: "module" tells acorn that the file uses import and export.
3. Lines 5 to 7 keep only the imports. Each path like ./math.js becomes a full path like /src/math.js.
4. Lines 11 and 12 skip a file that was already visited, and mark this one as visited.
5. Line 13 visits every file that this file imports, first.
6. Line 14 adds this file to the order, after the files it imports.

1(function(modules) {2  const cache = {};3  function require(id) {4    if (cache[id]) return cache[id].exports;5    const module = { exports: {} };6    cache[id] = module;7    modules[id](require, module, module.exports);8    return module.exports;9  }10  require("/src/main.js");11})({12  "/src/setup.js": function(require, module, exports) {13    console.log("setup side effect");14  },15  "/src/math.js": function(require, module, exports) {16    const version = "1.0.0";17    18    function add(a, b) {19      return a + b;20    }21    exports.add = add;22    exports.version = version;23  },24  "/src/format.js": function(require, module, exports) {25    const { version: version } = require("/src/math.js");26    function label(value) {27      return "v" + version + ": " + value;28    }29    exports.label = label;30  },31  "/src/main.js": function(require, module, exports) {32    require("/src/setup.js");33    const { add: add } = require("/src/math.js");34    const { label: label } = require("/src/format.js");35    console.log(label(add(2, 3)));36  }37});

The output is old-style on purpose, so you can read it:

• An object holds one function for each file. The file's path is the key.
• A small require(id) function runs a file's function. The file puts what it exports on module.exports. Then require saves that in cache, so asking for the same file again doesn't run it twice.
• Line 10 of the bundle calls require("/src/main.js") to start the app.

Real bundlers write smaller, faster code. But this one shows the main idea with nothing hidden. It only knows its own four files. It doesn't handle cycles, export ... from lines, or npm packages.

Tree shaking means leaving out exports that no code uses. Think of the module graph as a tree: shake it, and the parts nothing holds on to fall off.

It works well with ES modules. Their import and export lines use fixed names, so the bundler can read them without running any code. Tree shaking has four steps:

1. Start at the entry.
2. Mark each export that the entry imports and uses.
3. Look inside those exports for more imports, and mark those too.
4. Leave out every export that was never marked.

const exportsFromMath = ["add", "multiply"];
const used = new Set(["add"]);
console.log(exportsFromMath.filter((name) => used.has(name)).join(", "));

Line 1 lists the two exports of math.js. Line 2 makes a set of used names that holds only add. Line 3 keeps the names that are in the set, and prints add.

This code is only a model of the idea, not a real bundler. A real bundler may also keep a file whose exports are all unused, if the file does other work when it loads. You'll see why below.

1const exportsInGraph = [Run2  "math.version",3  "math.add",4  "math.multiply",5  "format.label",6  "format.loud",7];8 9const used = new Set(["math.add", "format.label"]);10used.add("math.version");11 12const kept = exportsInGraph.filter((name) => used.has(name));13const dropped = exportsInGraph.filter((name) => !used.has(name));14console.log(kept.join(", "));15console.log(dropped.join(", "));

1(function(modules) {2  const cache = {};3  function require(id) {4    if (cache[id]) return cache[id].exports;5    const module = { exports: {} };6    cache[id] = module;7    modules[id](require, module, module.exports);8    return module.exports;9  }10  require("/src/main.js");11})({12  "/src/setup.js": function(require, module, exports) {13    console.log("setup side effect");14  },15  "/src/math.js": function(require, module, exports) {16    const version = "1.0.0";17    18    function add(a, b) {19      return a + b;20    }21    exports.add = add;22    exports.version = version;23  },24  "/src/format.js": function(require, module, exports) {25    const { version: version } = require("/src/math.js");26    function label(value) {27      return "v" + version + ": " + value;28    }29    exports.label = label;30  },31  "/src/main.js": function(require, module, exports) {32    require("/src/setup.js");33    const { add: add } = require("/src/math.js");34    const { label: label } = require("/src/format.js");35    console.log(label(add(2, 3)));36  }37});

Some files do work as soon as they are imported. For example, they add styles to the page or add a name to a shared list. Work like this is called a side effect. A package can tell bundlers whether its files have side effects. It does this with the sideEffects field in its package.json file.

1{2  "name": "tiny-ui-kit",3  "sideEffects": false4}

const registered = [];
registered.push("checkout");
console.log(registered.join(", "));

Line 1 makes an empty list. Line 2 adds checkout to it. Line 3 prints checkout. Now imagine lines 1 and 2 in their own file. That file exports nothing. But removing it would leave the list empty. So the sideEffects field is about whole files, while tree shaking looks at single exports.

"sideEffects": false is a promise from the package. It says: if no code uses a file's exports, it is safe to leave that file out, even if something imports it. If the promise is wrong, parts of the app can disappear, such as CSS or code that registers something.

{
  "name": "tiny-ui-kit",
  "sideEffects": ["**/*.css", "./src/register.js"]
}

This version lists the files that do have side effects: every CSS file, and register.js. The bundler keeps those, and can still leave out other unused files. The package.json file is a settings file for tools. It doesn't run in the browser.

Before you promise "sideEffects": false, check a production build. A development build may keep code that the production build removes.

A /*#__PURE__*/ comment is a smaller promise about one function call. It is read by the minifier, the tool that makes code smaller. It says: if nothing uses this call's result, you can remove the call.

1const button = /*#__PURE__*/ createButton({ variant: "ghost" });2export const used = button.label;3export const unused = /*#__PURE__*/ createChartTheme();

Line 2 uses button, so the call on line 1 stays. Line 3 exports unused. If no other file imports unused, the minifier may remove the call on line 3.

Older Node.js code uses CommonJS: require() and module.exports. CommonJS is harder to tree-shake. A require() path can be built while the code runs. Code can also change module.exports at any time. Tools still handle common cases. But ES modules have a fixed shape, so tools can trust them more.

An import line at the top of a file is a static import. The file it names always loads with the app.

A dynamic import, written import("./file.js"), loads a file later, while the code runs. It returns a promise: an object that receives the file's exports once the file has loaded.

A bundler sees import() as a place where it can split the app. It can put that file, and the files it imports, into a separate chunk. Then heavy code waits until the user needs it. The final split can still differ: a very small file, or a file other code also uses, may end up in another chunk.

const entry = ["main", "cart"];
const lazy = ["profile"];
console.log(entry.join(" + ") + " | later: " + lazy.join(", "));

Line 1 lists the code that loads now: main and cart. Line 2 lists the code for later: profile. Line 3 prints main + cart | later: profile.

This is only a plan, not the real files a build makes. To see the real chunks, look at the files in your production build.

1const button = document.querySelector("#show-chart");2 3button.addEventListener("click", async () => {4  const { renderChart } = await import("./charts.js");5  renderChart();6});

In plain words, line by line:

1. Line 1 finds the button on the page.
2. Line 3 runs the code inside only when someone clicks the button.
3. Line 4 loads charts.js. await pauses this function until the file has arrived.
4. Line 5 calls renderChart() from that file, which prints chart chunk loaded.

In a production build, chunk file names usually include a content hash. A content hash is a short code made from the file's contents, like a1 in cart.a1.js. If the chart code changes, its chunk gets a new name. Chunks that didn't change keep their old names.

Loading a chunk can fail. For example, a new version of the site may have removed an old chunk. So catch the error from import(), and offer the user a reload or a retry. The dynamic import lesson covers import() itself in more detail.

const previous = { cart: "cart.a1.js", profile: "profile.b2.js" };
const next = { ...previous, profile: "profile.c3.js" };
console.log(next.cart === previous.cart, next.profile === previous.profile);

Line 1 holds the old file names. Line 2 copies them and gives profile a new name. Line 3 compares the names. The cart name is the same, and the profile name is different, so it prints true false.

In real builds, a file that imports the profile file can get a new name too, because it now holds the profile file's new name. Send hashed files with a long cache time, so browsers keep them. But always send a fresh copy of the HTML page, so browsers find the new file names.

Vite is two things: a development server and a build tool. A development server is a program that runs your app on your own computer while you work on it. While you work, Vite:

• sends your files to the browser as native ES modules, without bundling the whole app;
• changes each file, for example from TypeScript to JavaScript, only when the browser asks for it;
• bundles your npm packages once, ahead of time, so a package made of hundreds of small files doesn't slow down every page load. This is called pre-bundling.

For the final build, older Vite versions used Rollup to bundle, and esbuild for many fast transforms.

const mode = "production";
const tasks = mode === "production" ? ["bundle", "minify", "hash"] : ["transform", "reload"];
console.log(tasks.join(" -> "));

Line 1 sets the mode to production. Line 2 picks the list of jobs for that mode. Line 3 prints bundle -> minify -> hash. Change line 1 to "development", and it prints transform -> reload. This is a simple list, not how Vite really works inside.

In development, hot module replacement (HMR) swaps in a file you just edited, without reloading the whole page. In production, the build makes the files you put online.

The table below compares the tools. Read each row as: the tool, its main job, and a simple way to think about it.

In short:

• esbuild is written in the Go language, and is known for being very fast.
• Rollup was made for ES modules first. It has a well-tested plugin system and writes very clean output for libraries.
• Vite combines tools like these. You get fast feedback while you work, and small files for production, without writing a big config file.
• Rolldown is Vite 8's bundler, written in the Rust language. It is a separate project, not a new name for Rollup.
• Parcel is another build tool. It starts from an HTML file and needs very little setup.

Pick a tool by what your project needs and which plugins you use, not by speed alone.

webpack is an older, very popular bundler. Its words are still used everywhere. Even when a framework hides the config, you'll hear about entries, loaders, plugins, chunks, and HMR.

Next.js, the framework that builds this site, uses a bundler underneath. Turbopack and Rspack are newer bundlers written in Rust. They keep webpack's familiar ideas and aim to make builds faster.

Each row of the table below is one webpack word and what it means.

1module.exports = {2  mode: "production",3  entry: "./src/main.js",4  output: {5    filename: "[name].[contenthash].js",6    clean: true,7  },8  module: {9    rules: [{ test: /\.css$/, use: ["style-loader", "css-loader"] }],10  },11  plugins: [new HtmlWebpackPlugin()],12};

In plain words, line by line:

1. Line 2 picks production mode.
2. Line 3 names the entry file.
3. Line 5 adds a content hash to each output file name.
4. Line 9 sends every .css file through two loaders.
5. Line 11 adds a plugin that writes the HTML page.

This config runs in Node.js during the build, not in the browser, so it can't run in the editor here. To use the plugin on line 11, a real project must first install and import HtmlWebpackPlugin.

The code a bundler writes is not the code you wrote. Names may be shorter, and many files may be joined into one. A source map is a file that links the two. For a place in the built code, it says which file, line, and column it came from. DevTools, the browser's tools for developers, uses it to show you your own code.

const original = { file: "cart.ts", line: 3 };
const generated = { file: "app.js", line: 1 };
console.log(generated.file + ":" + generated.line + " -> " + original.file + ":" + original.line);

Line 1 describes a place in the code you wrote: line 3 of cart.ts. Line 2 describes the matching place in the built code: line 1 of app.js. Line 3 prints app.js:1 -> cart.ts:3.

Real maps also store columns. And not every place in the built code has a match. DevTools uses the map only to show where code came from. The browser still runs the built code, not your original files.

The table below lists the parts of a source map you'll meet. Each row names one part and says what it does.

The built file usually points to its map with a comment on its last line.

1console.log("compiled file");2//# sourceMappingURL=app.js.map

Line 1 is the built code. Line 2 is the comment that tells DevTools to load app.js.map.

The part of the map that does the real work is mappings. It is one long string, made of short pieces called segments. Each segment stores a few small whole numbers, written in a format called Base64 VLQ. It is a way to write numbers as letters. A bit, used below, is a single 0 or 1 inside a number.

• Each letter stands for a number from 0 to 63. A is 0, B is 1, C is 2, D is 3.
• Each number is a difference from the one before, not a full position. That keeps the numbers small.
• One bit of each letter, the bit worth 32, says "this number goes on in the next letter".
• The lowest bit of each number says whether it is positive (0) or negative (1).

The decoder below is short enough to read. This lesson's test also checks it against a real source map made by the TypeScript compiler.

1const BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";2 3function decodeVlqSegment(segment) {4  const values = [];5  let value = 0;6  let shift = 0;7  for (const char of segment) {8    const digit = BASE64.indexOf(char);9    const continuation = digit & 32;10    value += (digit & 31) << shift;11    if (continuation) {12      shift += 5;13      continue;14    }15    const negative = value & 1;16    values.push((negative ? -1 : 1) * (value >> 1));17    value = 0;18    shift = 0;19  }20  return values;21}22 23console.log(JSON.stringify(decodeVlqSegment("C")));24console.log(JSON.stringify(decodeVlqSegment("D")));25console.log(JSON.stringify(decodeVlqSegment("AAAA")));

1import ts from "typescript";2 3const result = ts.transpileModule("const answer: number = 40 + 2;", {4  compilerOptions: { sourceMap: true },5  fileName: "answer.ts",6});7console.log(JSON.parse(result.sourceMapText).mappings);

Line 3 turns one line of TypeScript into JavaScript. Line 4 asks for a source map too. Line 7 prints the map's mappings string. This code needs the typescript package, so it runs in Node.js, not in the editor here.

Most teams never write a bundler. Instead they:

• pick the tool's defaults;
• add or change plugins;
• decide which source maps to publish;
• watch how big the output files are.

A minifier makes code smaller. It removes spaces and shortens names, without changing what the code does. Terser and esbuild are common minifiers. By default, Vite 8 uses its own tools, Rolldown and Oxc.

File names should include content hashes. Make source maps public only if you have decided to. Many apps instead upload hidden maps to an error tracker: a service that collects errors from users' browsers.

const cart = [2, 3];
console.log(cart.reduce((total, price) => total + price, 0));

Line 1 holds two prices. Line 2 adds them with reduce, which walks the list and keeps a running total. It prints 5. A minifier may shorten names and remove spaces, but the result must stay 5. It doesn't remove the adding.

To measure what minifying saves, compare the size of the output files after compression. Don't count the lines you wrote.

1import { defineConfig } from "vite";2import react from "@vitejs/plugin-react";3 4export default defineConfig({5  plugins: [react()],6  build: {7    sourcemap: "hidden",8    rolldownOptions: {9      output: { entryFileNames: "assets/[name].[hash].js" },10    },11  },12});

In plain words, line by line:

1. Line 5 adds the React plugin.
2. Line 7 writes source maps, but leaves out the comment that points to them.
3. Line 9 adds a content hash to each output file name.

This file runs in the build tool, not in the browser, so it can't run in the editor here. Vite 8 reads output settings from rolldownOptions. Upload hidden maps to your error tracker if you need error reports that point to your own code.

The table below compares four ways to ship source maps. Read each row as: the choice, when it helps, and what to watch for.

Common misconceptions

• “Bundling is the same as transpiling.” They often happen in the same build. But bundling changes how code is split into files. Transpiling changes how the code is written, for example from TypeScript to JavaScript.
• “A bundler runs in the user's browser.” The bundler runs before the site goes online. The browser only gets the files the bundler wrote.
• “Tree shaking removes every unused line.” Tree shaking is careful. It keeps code that might have side effects, code reached in ways it can't predict, and most CommonJS code.
• “Source maps are always safe to publish.” They can show anyone your original code, comments, and file names. Decide on purpose whether maps are public or hidden.
• “Vite means no bundling.” While you work, Vite mostly avoids bundling the whole app. But the production build still writes bundled chunks.

These four words often show up together. The table below says what job each one does.

Key takeaways

• A bundler follows imports from the entry, and turns your many files into a few files the browser can load quickly.
• Vite is a development server and a build tool. As of this lesson, Vite 8 uses Rolldown by default.
• Tree shaking leaves out unused exports. It works best with ES modules, because their imports and exports use fixed names.
• A dynamic import() lets the bundler move code into a chunk that loads later. Check the build to see the real chunks.
• Source maps lead from the built code back to your own files. Decide on purpose whether to publish them.

Up next: Transpilers & polyfills. There you'll learn the difference between changing how code is written and adding features that older browsers lack.