stack/packages/mosaic/framework/skills/tsdown/references/guide-migrate-from-tsup.md

Migrate from tsup

Migration guide for switching from tsup to tsdown.

Overview

tsdown is built on Rolldown (Rust-based) vs tsup's esbuild, providing faster and more powerful bundling while maintaining compatibility.

Automatic Migration

Single Package

npx tsdown-migrate

Monorepo

# Using glob patterns
npx tsdown-migrate packages/*

# Multiple directories
npx tsdown-migrate packages/foo packages/bar

Migration Options

• [...dirs] - Directories to migrate (supports globs)
• --dry-run or -d - Preview changes without modifying files

Important: Commit your changes before running migration.

Key Differences

Default Values

Option	tsup	tsdown
format	['cjs']	['esm']
clean	false	true
dts	false	Auto-enabled if types/typings in package.json
target	Manual	Auto-read from engines.node in package.json

New Features in tsdown

Node Protocol Control

export default defineConfig({
  nodeProtocol: true, // Add node: prefix (fs → node:fs)
  nodeProtocol: 'strip', // Remove node: prefix (node:fs → fs)
  nodeProtocol: false, // Keep as-is (default)
});

Better Workspace Support

export default defineConfig({
  workspace: 'packages/*', // Build all packages
});

Migration Checklist

1. Backup your code - Commit all changes
2. Run migration tool - npx tsdown-migrate
3. Review changes - Check modified config files
4. Update scripts - Change tsup to tsdown in package.json
5. Test build - Run pnpm build to verify
6. Adjust config - Fine-tune based on your needs

Common Migration Patterns

Basic Library

Before (tsup):

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],
  dts: true,
});

After (tsdown):

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'], // ESM now default
  dts: true,
  clean: true, // Now enabled by default
});

With Custom Target

Before (tsup):

export default defineConfig({
  entry: ['src/index.ts'],
  target: 'es2020',
});

After (tsdown):

export default defineConfig({
  entry: ['src/index.ts'],
  // target auto-reads from package.json engines.node
  // Or override explicitly:
  target: 'es2020',
});

CLI Scripts

Before (package.json):

{
  "scripts": {
    "build": "tsup",
    "dev": "tsup --watch"
  }
}

After (package.json):

{
  "scripts": {
    "build": "tsdown",
    "dev": "tsdown --watch"
  }
}

Feature Compatibility

Supported tsup Features

Most tsup features are supported:

• ✅ Multiple entry points
• ✅ Multiple formats (ESM, CJS, IIFE, UMD)
• ✅ TypeScript declarations
• ✅ Source maps
• ✅ Minification
• ✅ Watch mode
• ✅ External dependencies
• ✅ Tree shaking
• ✅ Shims
• ✅ Plugins (Rollup compatible)

Missing Features

Some tsup features are not yet available. Check GitHub issues for status and request features.

Troubleshooting

Build Fails After Migration

1. Check Node.js version - Requires Node.js 20.19+
2. Install TypeScript - Required for DTS generation
3. Review config changes - Ensure format and options are correct
4. Check dependencies - Verify all dependencies are installed

Different Output

• Format order - tsdown defaults to ESM first
• Clean behavior - tsdown cleans outDir by default
• Target - tsdown auto-detects from package.json

Performance Issues

tsdown should be faster than tsup. If not:

1. Enable isolatedDeclarations for faster DTS generation
2. Check for large dependencies being bundled
3. Use skipNodeModulesBundle if needed

Getting Help

• GitHub Issues - Report bugs or request features
• Documentation - Full documentation
• Migration Tool - Source code

Acknowledgements

tsdown is heavily inspired by tsup and incorporates parts of its codebase. Thanks to @egoist and the tsup community.