English for Rollup Bundler Developers
Vocabulary for developers configuring Rollup — tree-shaking, ESM output, plugins, and code-splitting — for teams discussing library bundling in English.
Rollup conversations center on one recurring question: “why is this dead code still in the bundle?” Answering it precisely requires vocabulary about side effects and module boundaries, not just “the bundler is being weird.”
Bundling Basics
Tree-shaking — the process of statically analyzing ES module imports/exports to eliminate code that is never actually used, keeping the final bundle smaller.
“That import is unused in this file, but tree-shaking can’t remove it because the module has side effects the bundler can’t prove are safe to skip.”
ESM output — producing a bundle in ECMAScript Module format (using import/export), as opposed to CommonJS or UMD, which is the format Rollup was originally built around and still handles best.
“We’re publishing this library with ESM output as the primary format — it’s what makes tree-shaking possible for anyone consuming it.”
Side effect — code that does something observable beyond just exporting values (like mutating a global or running on import), which prevents a bundler from safely removing it even if the export looks unused.
“Mark this file as side-effect-free in package.json only if you’re sure — if it secretly patches a global, tree-shaking it out will silently break consumers.”
Plugins and Config
Plugin — a piece of code that hooks into Rollup’s build pipeline to transform code, resolve non-JS imports, or add custom behavior (like handling CSS or TypeScript).
“Without the TypeScript plugin, Rollup has no idea what to do with a
.tsfile — it just sees an unknown extension.”
External dependency — a package explicitly excluded from the bundle and left as an import for the consumer’s own bundler or runtime to resolve, common for libraries that shouldn’t bundle their own dependencies.
“Mark
reactas external — we don’t want every consumer of this library shipping their own copy of React inside our bundle.”
Entry point — the file (or files) Rollup starts its dependency graph traversal from, determining what actually ends up reachable — and therefore includable — in the output.
“Nothing in that file will be tree-shaken correctly if it’s not reachable from an entry point — right now it’s dead code the bundler doesn’t even know exists.”
Output Shape
Code-splitting — breaking the bundle into multiple output chunks, often along dynamic import() boundaries, so consumers only load what a given code path actually needs.
“That dynamic import should create a separate chunk — if it’s still landing in the main bundle, check the code-splitting config.”
Chunk — one of potentially several output files Rollup produces, as opposed to a single monolithic bundle; shared dependencies between entry points are often extracted into their own chunk.
“There are three chunks here because two entry points share a common dependency Rollup pulled out on its own.”
Common Mistakes
- Blaming tree-shaking for a bundle-size problem without checking whether the offending module has side effects that legitimately prevent removal.
- Forgetting to mark peer dependencies as external, causing a library to ship duplicate copies of frameworks like React inside its own bundle.
- Assuming everything reachable from any file gets tree-shaken, when only code reachable from a declared entry point is even analyzed.
Practice Exercise
- Explain, in two sentences, why marking a dependency as external matters for a published library.
- Write a short PR comment diagnosing an oversized bundle as a missing
externalconfig rather than a tree-shaking bug. - Draft a message explaining why a file with global side effects can’t be safely tree-shaken even if its exports look unused.