Switching from tsup to tsdown

About tsdown

tsdown is a new bundler from the void(0) folks, the new company formed out of the Vite/Vitest/Rolldown/Oxc ecosystem.

tsdown aims to be:

• “blazing fast”
• simple (if you want lots of config, or aren’t bundling a library, go use Rolldown/Vite), and to be lightning fast.
• easy to migrate to from existing bundlers (mainly, but not exclusively, tsup)

If you couldn’t tell from the name, it is inspired by tsup, and is a batteries-included library bundler. It sits on top of Rolldown, which is the Rollup-inspired bundler at the heart of the next version of Vite. So you probably want Vite+Rolldown if you are building an app, and tsdown if you are building a library.

I have an abandoned comparison of all the new, fast Rust bundlers that I’ll never finish because most of them are missing things that were important to me (like TypeScript support) and I found the comparison pointless. tsdown (and Rolldown), like everything from the Vite folks, delivers exactly the right set of features, so its the only one I’m going to write about.

Why You Should Use tsdown

How Easy Is Migration?

Really easy! Here’s everything I did to migrate from tsup to tsdown in my monorepo:

1. Enable "isolatedDeclarations": true in your tsconfig

2. Fix any errors caused by enabling this⁴. That means typing the exports of every file, even if they can be inferred. For these I used VS Code’s auto-fixer to infer the type, and I believe this worked for everything.

3. For zod types, the inferred type is huge and has to be kept in sync with the zod schema. That’s just a cost of having isolated declarations while using runtime type systems. Example here.

4. Migrate your tsup config to tsdown, e.g. pnpm dlx tsdown migrate ./tsup.config.node.ts

5. Consolidate .js + .d.ts build scripts:

   1
   "build": "tsup --config build-config/tsup.config.node.ts",
   2
   "build:types": "tsc --project tsconfig.declarations.json",
   3
   "build": "tsdown --config ../build-config/tsdown.config.node.ts",

   Note that tsdown requires an explicit relative path to the config while tsup just figures it out for you

6. If you use the onSuccess hook to run a script to build types, just remove it

7. For Node.js libraries where you don’t bundle the code⁵, you’ll have to switch from tsup’s bundle: false to tsdown’s unbundle: true.

8. The most important step: validation. Compare the tsup and tsdown output and make sure it’s correct, as best you can. Make sure you have automated tests that exercise the transpiled files (i.e. if you use vitest you should have one test that tests the package exports and doesn’t just import ts files directly). Here’s an example from my repo. Consider using are-the-types-wrong validation⁶ in CI if you aren’t already.

9. Lastly, consider publishing major versions of your packages, especially if you can’t manually verify every line of bundler output. This is a really tricky decision and you’ll have to decide what’s right for your package. If you can manually verify all the output, this is probably unnecessary, but you want to avoid shipping a patch version that has some subtle backwards-incompatibility due to the bundler change.

How Mature is tsdown?

I only found a couple of bugs:

1. https://github.com/rolldown/tsdown/issues/198 - this is a minor bug with having a shared configuration. It was impossible to miss and was fixed quickly.
2. https://github.com/rolldown/tsdown/issues/256 - this is a critical bug that causes incorrect output. Without proper testing in place you could possibly miss it, but the bug is not subtle and the simplest of tests that exercise the actual package output in the dist directory will always catch this. The team published a fix to npm in ~2 days.

So, I guess it depends on your risk tolerance and how much automated testing you have in place. For my barely-used, well-tested packages that make up my little garden: it’s mature enough. You might want to wait for the 1.0 🤷🏽‍♀️.