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. After replacing the configuration and adding outExtensions to keep the original filenames, all exports and declarations remained unchanged. Artifact size grew, but consumer compatibility was maintained.

Problem

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

Outcome

The migration was straightforward in terms of configuration but required explicit filename mapping to preserve the package contract. The smoke test confirmed that consumers would receive the same API and declarations. Artifact size increased by ~23.6% and build time improved marginally, but the primary benefit was maintaining compatibility.

Workflow

• 1. Replace tsup dependency with tsdown.
• 2. Rename tsup.config.ts to tsdown.config.mts and adjust options (entry, format, dts, clean, outDir, target, banner).
• 3. Run pnpm build – observe that output filenames differ from package.json exports.
• 4. Add outExtensions to map cjs outputs to .js and dts outputs to .d.ts, preserving original filenames.
• 5. Run the existing packed‑package smoke test to verify exports, runtime, and declarations.
• 6. Measure artifact size and build time 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 added outExtensions to preserve the existing filenames

Source

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

Source