Migrating a Real TypeScript OSS Library from tsup to tsdown

Description and use

Migrating is‑kit from tsup to tsdown required preserving output filenames to keep the package contract intact. Using outExtensions and a packed‑package smoke test ensured the contract remained unchanged, though the artifact size increased.

Problem

Preserve the published package contract while switching the build tool from tsup to tsdown.

Outcome

The migration was straightforward in terms of code changes but required careful handling of output filenames to keep the package contract intact. A smoke test that installs the packed tarball verified that consumers still received the same API and types.

Workflow

• Replace tsup dependency with tsdown
• Rename tsup.config.ts to tsdown.config.mts
• Copy most config options (entry, format, dts, clean, outDir, target, banner)
• Run pnpm build
• Observe that output filenames changed
• Add outExtensions to map cjs to .js and dts to .d.ts
• Run pnpm build again
• Run packed‑package smoke test to verify exports, types, runtime, and declaration banner

Evidence

The first tsdown build succeeded while silently changing files that were already part of the package's public contract.

Source

The config migration was small. Preserving the package contract was the interesting part.

Source

I used outExtensions: ({ format }) => ({ dts: format === 'cjs' ? '.d.ts' : '.d.mts', js: format === 'cjs' ? '.js' : '.mjs', }),

Source

After the migration, I expanded the test to verify more of the package contract

Source

The tsdown output retained more comments and region markers than the previous tsup output.

Source