Migrating from tsup to tsdown

Knowledge base for AI agents to migrate tsup projects to tsdown — the Rolldown-powered library bundler.

Target Version: Two-Stage Migration

tsdown v0.23 removed all previously-deprecated tsup compatibility options — bundle, outExtension, publicDir, removeNodeProtocol, injectStyle, and skipNodeModulesBundle are no longer recognized. They fail TypeScript type checking and are silently ignored at runtime, so a missed mapping on v0.23+ produces wrong output without any error. Migrating directly to v0.23+ is therefore unsafe. tsdown v0.22.14 is the last version that still accepts these options and flags each one with a deprecation warning, making it the safe migration checkpoint. Migrate in two stages:

1. Stage 1 — migrate on tsdown@0.22.14: Install tsdown@0.22.14, migrate the config per the tables below, run a build, and resolve every deprecation warning by mapping each flagged tsup option to its real tsdown equivalent. The warnings are the completeness check — the migration is not done until the build produces zero warnings.
2. Stage 2 — upgrade to the latest tsdown (^0.23.0 or newer): Only after a warning-free build on 0.22.14. Since the config no longer uses any removed compat options, the silent-ignore behavior of v0.23+ is no longer a risk.

Runtime Requirement

tsdown requires Node.js ^22.18.0 || ^24.11.0 || >=26.0.0 to run (build-time only) — that is, Node.js 22.18+, 24.11+, or 26+. Odd-numbered and EOL release lines (e.g. Node.js 23, 25) are not supported. The bundled output can still target lower Node.js versions via the target option, so a library that previously supported Node.js 18 / 20 with tsup can continue to do so after migrating.

Recommended workflow when supporting Node.js 18 / 20:

• Build with Node.js 22+ in CI, setting an explicit target such as 'node18' or 'node20'.
• Test the built output (or the packed tarball) on the lower Node.js versions you need to support.