Migrating a Real TypeScript OSS Library from tsup to tsdown

说明与用途

将 is‑kit 库从 tsup 迁移到 tsdown 时，需要保留已发布的包合同，尤其是文件名和导出。通过在 tsdown 配置中添加 outExtensions，恢复了原始文件名，并通过 packed‑package smoke test 验证了消费者兼容性。产物大小增加了约 23.6 %，但主要收益是保持了消费者兼容性。

问题

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

结果

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.

工作流

• 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.

证据

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

来源

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

来源

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

来源

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

来源