Migrating a Real TypeScript OSS Library from tsup to tsdown

Description and use

Migrating the is‑kit library from tsup to tsdown required preserving the published package contract, especially file names and exports. Adding outExtensions in the tsdown config restored the original filenames, and a packed‑package smoke test verified consumer compatibility. The artifact size increased by ~23.6 %, but the main benefit was maintaining consumer compatibility.

Problem

Preserve the published package contract (file names, exports, declarations) when switching build tools from tsup to tsdown.

Outcome

The migration was small in code changes but required careful handling of output filenames via outExtensions to preserve the package contract. A packed‑package smoke test confirmed compatibility. Artifact size increased by ~23.6% and build time improved marginally, but the main benefit was maintaining consumer compatibility.

Workflow

• 1. Remove tsup dependency and install tsdown.
• 2. Replace tsup.config.ts with tsdown.config.mts and map options.
• 3. Run pnpm build – build succeeds but output filenames differ.
• 4. Add outExtensions to map cjs outputs to .js and dts to .d.ts.
• 5. Run pnpm build again – filenames match original contract.
• 6. Execute packed‑package smoke test to verify exports, runtime, and declarations.
• 7. Measure artifact size and build performance for comparison.

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