bundler-expertise

A standalone hub for driving JS/TS bundlers directly. For app builds inside Vite (which is Rollup + esbuild preconfigured) use [[vite-expertise]]; for bun build and Bun as the runtime see [[bun-expertise]].

When to use this

• Publishing an npm library and deciding how to build/ship it (formats, types, externals).
• Building a CLI, a serverless function, or a worker bundle outside an app framework.
• A consumer reports "Cannot use import statement" / dual-package / missing-types issues.
• Tree-shaking isn't removing dead code, or your bundle pulls in deps it shouldn't.

Documentation

Tool versions move fast; verify flags against the live docs before relying on them.

• esbuild: https://esbuild.github.io/ (API + bundle options)
• Rollup: https://rollupjs.org/ (config, output, tree-shaking)
• tsup: https://tsup.egoist.dev/ (the esbuild + rollup-plugin-dts wrapper)
• Node package.json exports: https://nodejs.org/api/packages.html#exports
• "Are the types wrong?": https://arethetypeswrong.github.io/ — audit a published package's exports/types map

WebFetch the relevant tool's options page for exact flag names — esbuild and tsup rename options between minors.

Mental model

The concepts that decide how to bundle and ship:

• Bundling ≠ type-checking. esbuild/swc/tsup transpile TS to JS fast but do not type-check and do not emit .d.ts from type analysis. tsc is the checker and the declaration emitter. Run both: tsc --noEmit for checking, the bundler (or tsc --emitDeclarationOnly) for output. See [[typescript-expertise]].
• Apps bundle deps; libraries don't. An app inlines its node_modules into one artifact. A library marks runtime/peer deps external so the consumer's copy is used and deduped — bundling React into a library ships two Reacts and breaks hooks.
• The output format is a contract with the consumer. ESM (import), CJS (require), IIFE/UMD (<script> global). A library usually ships ESM+CJS so both consumer styles resolve; the package.json exports map routes each.
• Tree-shaking needs proof of no side effects. A bundler keeps a module whose exports look unused if importing it might do something. "sideEffects": false (or a file list) is the promise that lets dead code drop.
• exports is authoritative. In modern Node/bundlers the exports map overrides main/module/types. Most "no IntelliSense" and "wrong entry" bugs are a malformed exports map.

Tooling & setup

Pick the tool:

Tool	Strength	Reach for it when
esbuild	extremely fast; bundles + transpiles TS/JSX	apps, CLIs, functions, dev speed; you don't need .d.ts
Rollup	best tree-shaking, plugin ecosystem, clean library output	publishing libraries; fine-grained output control
tsup	thin wrapper over esbuild + .d.ts via rollup-plugin-dts	the common case: a TS library, both formats, types, one config
Rolldown	Rust Rollup-compatible bundler (powers newer Vite)	Rollup semantics at esbuild-ish speed

Default for a TS library: tsup. It gives ESM+CJS, minification, source maps, and .d.ts from one small config. Drop to raw Rollup only when you need plugin control tsup doesn't expose.

// tsup.config.ts
import { defineConfig } from "tsup";

export default defineConfig({
  entry: ["src/index.ts"],
  format: ["esm", "cjs"], // ship both for broad consumer compat
  dts: true, // emit index.d.ts
  sourcemap: true,
  clean: true,
  treeshake: true,
  external: ["react"], // never bundle peers (see below)
});

Core idioms

Output formats — what to ship

• ESM — the modern default. Tree-shakeable by consumers, works in browsers and modern Node.
• CJS — still needed by older Node tooling. Ship it alongside ESM unless you're ESM-only on purpose.
• IIFE/UMD — only for a <script> tag / global usage. Most libraries don't need it.

Dual ESM+CJS is the safe library default. Going ESM-only is increasingly viable but excludes require() consumers — decide deliberately.

Tree-shaking and sideEffects

// package.json — your library promises no import-time side effects
{ "sideEffects": false }
// or list the files that DO have them (CSS, polyfills):
{ "sideEffects": ["*.css", "./src/polyfill.ts"] }

• Without "sideEffects": false, bundlers conservatively keep modules whose exports look unused — the #1 reason dead code survives.
• Author for tree-shaking: prefer named exports, avoid top-level work, keep side-effect imports (import "./thing") rare and declared.

external — never bundle peers

external: ["react", "react-dom", /^node:/],

• A library must not bundle its peer/runtime deps — mark them external so the consumer's copy is used and deduped.
• Mark Node built-ins external (node:fs, etc.) for Node-targeted builds.
• Apps are the opposite: they do bundle deps. external is mainly a library concern.

The package.json map — how consumers resolve your code

{
  "type": "module",
  "main": "./dist/index.cjs", // legacy CJS entry
  "module": "./dist/index.js", // legacy ESM hint (bundlers)
  "types": "./dist/index.d.ts", // legacy types entry
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js", // ESM consumers
      "require": "./dist/index.cjs", // CJS consumers
    },
    "./package.json": "./package.json",
  },
  "files": ["dist"],
  "sideEffects": false,
}

• exports is authoritative and overrides main/module. Keep the legacy fields for old tooling, but get exports right first.
• types must come first in each exports condition, ideally per format. A mismatched types path is the usual cause of "library works but has no IntelliSense."
• Conditions resolve top-to-bottom; import/require split ESM vs CJS. Add "default" last as a catch-all.
• List dist in files so you publish the build, not the source. Verify with npm pack --dry-run.

esbuild directly (apps, CLIs, functions)

import { build } from "esbuild";
await build({
  entryPoints: ["src/cli.ts"],
  bundle: true,
  platform: "node", // or "browser"
  target: "node20",
  format: "esm",
  outfile: "dist/cli.js",
  sourcemap: true,
  minify: true,
  packages: "external", // don't bundle node_modules deps (for Node apps)
});

• esbuild transpiles TS but does not type-check or emit .d.ts. Run tsc --noEmit for checking and tsc --emitDeclarationOnly (or tsup) for types. See [[typescript-expertise]].
• packages: "external" keeps node_modules out of a Node bundle; for a single-file deploy artifact, omit it to inline everything.

What NOT to do

• Bundling peer deps into a library. Mark them external; bundled React/Vue breaks consumers and bloats size.
• Omitting "sideEffects" and wondering why tree-shaking keeps dead code. Declare it.
• Trusting esbuild/swc to type-check. They only transpile — run tsc --noEmit separately. See [[typescript-expertise]].
• A wrong/missing types condition in exports. Consumers lose IntelliSense even though the code runs. Put types first.
• Letting main/module contradict exports. exports wins in modern resolvers — fix it first.
• Shipping ESM-only without realising it cuts off require() consumers. Fine if intentional, surprising if not.
• Publishing source instead of dist (or vice versa). Set files and verify with npm pack --dry-run.
• Reaching for raw Rollup config when tsup covers it. Start simple; escalate only for plugin needs.
• Hand-bundling app code that already runs through Vite. Use the framework's build.

Cross-references

• [[vite-expertise]] — app bundling (Vite = Rollup + esbuild preconfigured); library mode for in-app packages.
• [[bun-expertise]] — bun build as another bundler/target, and Bun as the runtime.
• [[typescript-expertise]] — tsc for type-check and .d.ts; isolatedModules for single-file transpilers; module resolution.
• [[web-workers-expertise]] — bundling worker entry points.