mcpField
T
tsdown

tsdown

github.com/oakoss开发2186 次安装12 周前更新
代码仓库

关于 tsdown

tsdown 是基于 Rolldown 构建的 TypeScript 和 JavaScript 库打包器，面向库开发者。它提供多种模块格式、声明文件生成和 package.json 导出配置，并带有默认构建设置。

主要功能

  1. 01生成 ESM、CJS、IIFE 和 UMD 格式
  2. 02生成 TypeScript 声明文件
  3. 03生成 package.json 导出配置
  4. 04监视文件并自动重新构建
  5. 05运行包校验并生成体积报告

适用场景

  1. 01为 npm 打包 TypeScript 库
  2. 02以 ESM 和 CJS 格式发布包
  3. 03通过监视模式构建命令行工具

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/oakoss/agent-skills --skill tsdown

安装后在 Claude Code 中输入/tsdown确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
advanced-features.md
configuration.md
declaration-files.md

详细介绍

tsdown

概述

tsdown 是一个基于 Rolldown（基于 Rust）构建的优雅库打包器，为构建 TypeScript 和 JavaScript 库提供完整的开箱即用解决方案。它负责源码转换、生成多种输出格式（ESM、CJS、IIFE、UMD）、生成 TypeScript 声明文件，以及生成 package.json 的 exports 字段，并提供合理的默认配置。

适用场景： 为 npm 构建 TypeScript 库、生成声明文件、生成同时支持 ESM/CJS 的包、打包 CLI 工具、以监听模式开发库、从 tsup 迁移。

不适用场景： 应用打包（直接使用 Vite/Rolldown）、服务端渲染框架（使用框架的打包器）、需要 Webpack 特定功能的项目、无需打包的简单脚本。

快速参考

模式API要点
基本构建npx tsdown自动检测 src/index.ts 入口
配置文件tsdown.config.ts使用 defineConfig() 确保类型安全
入口点entry: ['src/index.ts']使用字符串、数组或对象指定具名入口
输出格式format: ['esm', 'cjs']支持 ESM、CJS、IIFE、UMD
声明文件dts: true从 package.json 的 types 字段自动检测
固定扩展名fixedExtension: true强制使用 .mjs/.cjs 和 .d.mts/.d.cts
外部依赖external: ['react']默认将 node_modules 设为外部依赖
打包依赖noExternal: ['lodash-es']强制打包指定依赖
目标target: 'node18'ES 版本或 Node 版本
平台platform: 'node'node、browser 或 neutral
压缩minify: true单独启用摇树优化
摇树优化treeshake: true消除无用代码
Source Mapsourcemap: true内联或外部 Source Map
监听模式tsdown --watch文件更改时自动重新构建
清理输出clean: true构建前移除输出目录
验证--publint --attw构建后检查包质量
大小报告--report显示 gzip/brotli 压缩统计的包大小
多个配置defineConfig([...])使用配置数组生成不同输出
动态配置defineConfig((opts) => {})接收 CLI 选项的函数
编程式 APIimport { build }在 Node.js 脚本中使用
页眉/页脚banner: { js: '...' }在输出文件开头添加或末尾追加内容
onSuccess 钩子onSuccess: async () => {}构建成功后运行
Node 协议nodeProtocol: true为内置模块导入添加或移除 node: 前缀

常见错误

错误正确做法
使用双格式时未设置 fixedExtension同时发布 ESM 和 CJS 时，对 .mjs/.cjs 使用 fixedExtension: true
将所有 node_modules 打包到库输出中默认情况下依赖项为外部依赖；仅对特定依赖使用 noExternal
未配置 TypeScript 就使用 dts: true确保存在 tsconfig.json，且包含正确的 compilerOptions
为现代语法设置过低的 target将 target 与最低支持的 Node/浏览器版本保持一致
package.json 中缺少 types 字段添加 types 或 exports 中的 types 条件以解析声明
更改格式前未清理输出使用 clean: true，避免残留之前构建的文件
为 Node 内置模块内联设置 external在 platform: 'node' 下，Node 内置模块（如 node:fs）会自动标记为外部依赖
在 CI 中使用交互式 CLI 标志CI 构建时使用配置文件或非交互式 CLI 标志

委派

  • 构建配置审查：使用 Task agent 分析 tsdown 配置是否正确
  • 包发布：使用 Explore agent 验证 package.json 的 exports 和 types 字段
  • 从 tsup 迁移：使用 Task agent 将 tsup 选项映射为对应的 tsdown 选项

参考资料

评论

支持 Markdown