tsup

tsup is a command-line bundler that packages TypeScript and JavaScript libraries with no configuration required. It wraps esbuild for the heavy lifting and layers on library-specific concerns esbuild doesn’t handle out of the box: multiple output formats (CJS, ESM, IIFE) in a single run, .d.ts declaration generation, code splitting, watch mode, and CLI entry bundling.

Because of its no-config defaults and speed, tsup became one of the most widely adopted ways to ship a TypeScript npm package, used by countless open-source libraries as their build step. The README now flags the project as no longer actively maintained, pointing users toward tsdown as a successor, but tsup remains in heavy production use (multi-million weekly npm downloads) and its GitHub issues/discussions stay active.

What You Get

• Zero-config bundling driven entirely by CLI flags or an optional tsup.config.ts
• Simultaneous CJS, ESM, and IIFE output from a single build invocation
• Automatic .d.ts type declaration generation and rollup via API Extractor
• Watch mode with process restart and on-save rebuilds for CLI development
• Code splitting, tree-shaking, and shebang/CJS-interop handling for published packages

Common Use Cases

• Bundling a TypeScript npm library into CJS + ESM before publishing
• Building a Node.js CLI tool with a shebang-aware executable output
• Generating rolled-up .d.ts type declarations alongside compiled JS
• Watch-mode local development for a library consumed by another workspace package

Under The Hood

Architecture - The CLI entry (src/cli-main.ts, src/cli-default.ts) parses flags with cac, resolves an optional tsup.config.ts via bundle-require, then normalizes everything into NormalizedOptions inside src/index.ts. The core build() function fans out per-format esbuild runs coordinated through a PluginContainer (src/plugin.ts) that layers first-party esbuild plugins (shebang, cjs-splitting, swc-target, tree-shaking, size-reporter, terser) around the underlying esbuild calls in src/esbuild/, while a parallel path in src/tsc.ts/src/api-extractor.ts handles .d.ts generation and rollup outside the esbuild pipeline.

Tech Stack - Written in TypeScript targeting Node >=18, with esbuild ^0.27 as the bundling engine, Rollup ^4 used specifically for declaration-file rollup, chokidar/tinyglobby for watch and glob resolution, and optional peer dependencies (@swc/core, @microsoft/api-extractor, postcss, typescript) that unlock SWC transforms, API Extractor dts rollup, and PostCSS/Sass processing only when installed.

Code Quality - The test/ directory holds ten Vitest suites (index, css, dts, experimental-dts, svelte, graphql, shims, tsconfig, example) run via vitest run after a full build, covering most declared output modes; core modules use explicit TypeScript types (NormalizedOptions, Options) and a dedicated PrettyError/handleError path for user-facing failures, though inline code comments are sparse outside of edge-case explanations like the Windows taskkill handling in src/index.ts.

API Design - The public surface is deliberately small: a defineConfig() helper for config-file authors and CLI flags for everyone else, with sensible defaults (outDir: 'dist', CJS format) so a bare tsup src/index.ts produces a working build; the tradeoff is that discovering the full breadth of options (dts modes, splitting, multi-entry objects) requires consulting the external docs site rather than in-editor discovery, since most configuration is CLI-flag-driven rather than a single typed options object.