Bundling TypeScript Libraries: tsdown vs tsup

Both tsdown and tsup solve the same core problem: compiling TypeScript libraries into distributable JavaScript packages for npm. They remove the need for manual webpack or rollup configurations, offering zero-config defaults that work for most projects. However, they differ significantly in their underlying engines and plugin ecosystems. Let's compare how they handle the build process.

⚙️ Build Engine: Esbuild vs Rolldown

tsup is built on top of esbuild, a Go-based bundler known for extreme speed.

• It compiles code incredibly fast due to its parallel architecture.
• It has been stable for years and handles edge cases well.

# tsup: Uses esbuild under the hood
npx tsup src/index.ts

tsdown is built on top of rolldown, a Rust-based implementation of Rollup.

• It aims to match esbuild's speed while offering Rollup compatibility.
• It is newer and actively evolving, representing the next generation of JS tooling.

# tsdown: Uses rolldown under the hood
npx tsdown

🔌 Plugin Ecosystem: Esbuild vs Rollup

The choice of engine dictates which plugins you can use. This is often the deciding factor for complex projects.

tsup supports esbuild plugins.

• Great for simple transformations and loaders.
• Limited compared to the Rollup ecosystem for advanced use cases.

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

export default defineConfig({
  entry: ['src/index.ts'],
  esbuildPlugins: [
    // Custom esbuild plugin
    myEsbuildPlugin()
  ]
});

tsdown supports rollup plugins.

• Access to a vast library of existing Rollup plugins.
• Better for complex module resolution or legacy support.

// tsdown.config.ts
import { defineConfig } from 'tsdown';
import replace from '@rollup/plugin-replace';

export default defineConfig({
  entry: ['src/index.ts'],
  plugins: [
    // Native Rollup plugin support
    replace({ values: { __VERSION__: '1.0.0' } })
  ]
});

📝 Configuration & DX

Both tools aim for zero-config usage, but allow customization via config files.

tsup uses tsup.config.ts.

• Highly mature API with many options for splitting and shimming.
• Supports watching mode and CLI arguments extensively.

// tsup.config.ts
export default {
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],
  dts: true,
  splitting: false,
  clean: true
};

tsdown uses tsdown.config.ts.

• API is designed to feel familiar to tsup users.
• Focuses on simplicity and aligning with Vite/unjs standards.

// tsdown.config.ts
export default {
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],
  dts: true,
  clean: true
};

🛡️ Type Generation (dts)

Generating TypeScript definition files (.d.ts) is critical for library authors.

tsup uses tsup's built-in dts bundler (often leveraging rollup-plugin-dts internally).

• Reliable and handles most standard cases.
• Can be slower than the JS bundling step.

// tsup: Enable dts generation
export default {
  dts: true, // Generates .d.ts files
  dtsResolve: true // Resolves external types
};

tsdown integrates type generation directly into the rolldown pipeline.

• Aims for faster type bundling.
• Still maturing, but promises tighter integration.

// tsdown: Enable dts generation
export default {
  dts: true // Generates .d.ts files
};

🤝 Similarities: Shared Ground Between tsdown and tsup

Despite the engine differences, both tools share a common philosophy of simplifying library development.

1. 🚀 Zero-Config Defaults

• Both work immediately with npx without a config file.
• sensible defaults for CommonJS and ESM outputs.

# Both work with simple CLI commands
npx tsup src/index.ts
npx tsdown

2. 📦 Multiple Output Formats

• Support for CJS, ESM, and IIFE formats out of the box.
• Essential for libraries targeting Node.js and browsers.

// Both support format arrays
format: ['cjs', 'esm', 'iife']

3. 👀 Watch Mode

• Built-in file watching for local development.
• Rebuilds automatically on file changes.

# Both support watch flag
npx tsup --watch
npx tsdown --watch

4. 🧹 Cleanup Options

• Can clean the dist folder before building.
• Prevents stale files from being published.

// Both support clean option
clean: true

5. 🔗 External Dependencies

• Automatically mark dependencies and peerDependencies as external.
• Ensures your bundle doesn't include large libraries like React or Lodash.

// Both handle externals automatically based on package.json
// No extra config needed for standard deps

📊 Summary: Key Similarities

🆚 Summary: Key Differences

💡 The Big Picture

tsup is the safe, reliable choice 🛡️. It has powered thousands of libraries for years. If you need a build tool that just works today with minimal risk, tsup is the answer. The esbuild plugin ecosystem is sufficient for 90% of use cases.

tsdown is the forward-looking choice 🔭. It bets on the Rust-based future of JavaScript tooling. If you need specific Rollup plugins that esbuild doesn't support, or you want to align with the unjs ecosystem, tsdown is worth exploring. However, be prepared for occasional updates as the tool matures.

Final Thought: For most production libraries today, tsup remains the default recommendation due to its stability. Keep an eye on tsdown as the rolldown engine reaches version 1.0 — it may well become the new standard for performance and compatibility.