SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场tsdown

tsdown

编程与开发

查看项目

更新于 10-16 04:13

技能介绍

tsdown 是一个面向 TypeScript / JavaScript 库的打包工具，核心定位是“优雅的库打包器”，由 Rolldown 和 Oxc 驱动，强调极快的构建速度。它主要服务于需要发布到 npm 的库项目，以及需要生成类型声明、输出多种模块格式或优化产物的构建场景。

用途

  • 构建用于 npm 发布的 TypeScript / JavaScript 库。
  • 生成 TypeScript 声明文件（.d.ts）。
  • 为多种格式打包，包括 ESM、CJS、IIFE、UMD。
  • 通过 tree shaking 和 minify 优化 bundle。
  • 从 tsup 以较小改动迁移。
  • 构建 React、Vue、Solid 或 Svelte 组件库。

主要能力

  • 配置文件支持：可使用 defineConfig 定义 entry、format、dts、clean 等选项，配置文件形式为 tsdown.config.ts。
  • 输出格式：format 支持 ['esm']、['cjs']、['iife']、['umd'] 等组合。
  • 类型声明：dts: true 可生成声明文件，dts 还可接受 sourcemap、compilerOptions、vue 等配置。
  • 目标与平台：target 可设为 'es2020'、'esnext' 等；platform 可设为 'node' 或 'browser'。
  • 产物优化：treeshake 支持启用与自定义选项；minify 支持 true 或 'dce-only'。
  • 输出控制：outDir、outExtensions、sourcemap（true、'inline'、'hidden'）、watch、clean 等。
  • 依赖处理：deps.neverBundle、deps.alwaysBundle、deps.onlyBundle、deps.skipNodeModulesBundle，以及自动外部化 peer/依赖。
  • 输出增强：shims 提供 ESM/CJS 兼容（如 __dirname、__filename 等），cjsDefault 控制 CJS 默认导出，exports: true 可自动生成 package.json 的 exports 字段。
  • CSS 处理：实验性 css 配置支持预处理器、Lightning CSS、PostCSS 和代码分割，需 @tsdown/css；css.inject 可保留 JS 输出中的 CSS 导入。
  • 目录结构：unbundle: true 可保留目录结构；root 可控制输出目录映射。
  • 可执行文件：实验性 exe: true 可打包为独立可执行文件，跨平台需要 @tsdown/exe。
  • 包校验：publint、attw 可校验包。
  • 插件与钩子：支持 Rolldown、Rollup、Unplugin 插件，以及 build:before、build:done 等生命周期钩子。
  • 编程式 API：可从 Node.js 脚本中触发构建。
  • CI 环境：支持 CI 检测，以及 'ci-only'、'local-only' 等取值。

使用方式

  • 安装：pnpm add -D tsdown。
  • 基本使用：npx tsdown。
  • 指定配置：npx tsdown --config tsdown.config.ts。
  • 监听模式：npx tsdown --watch。
  • 从 tsup 迁移：npx tsdown-migrate。
  • 常用 CLI：tsdown（构建一次）、tsdown --watch（监听）、tsdown --config custom.ts（自定义配置）、tsdown --format esm,cjs（多格式）、tsdown -d lib（自定义输出目录）、tsdown --minify、tsdown --dts、tsdown --exe、tsdown --unbundle、tsdown src/index.ts（单入口）、tsdown src/*.ts（glob）、tsdown src/a.ts src/b.ts（多入口）、tsdown -W（workspace 模式）、tsdown -W -F my-package（过滤包）、tsdown --filter /^pkg-/（正则过滤）、tsdown --sourcemap、tsdown --clean、tsdown --from-vite、tsdown --tsconfig tsconfig.build.json。
  • 基础配置示例：entry: ['./src/index.ts']、format: ['esm', 'cjs']、dts: true、clean: true。
  • 多入口配置：entry 使用对象形式，如 { index: 'src/index.ts', utils: 'src/utils.ts', cli: 'src/cli.ts' }。
  • 浏览器库配置：format: ['iife']、globalName: 'MyLib'、platform: 'browser'、minify: true。
  • React 组件库配置：externalize react 与 react-dom，inputOptions.jsx.runtime 设为 'automatic'。
  • 保留目录结构：unbundle: true。
  • CI 感知配置：failOnWarn: 'ci-only'、publint: 'ci-only'、attw: 'ci-only'。
  • WASM：通过 rolldown-plugin-wasm 的 wasm() 插件支持。
  • CSS/Sass：使用 css.preprocessorOptions.scss.additionalData 等配置。
  • 独立可执行文件：exe: true；跨平台可执行文件使用 exe.targets 指定 platform、arch、nodeVersion。
  • 多配置：defineConfig 可导出数组。
  • 条件配置：defineConfig 可接收函数，根据 options.watch 等动态返回配置。
  • Monorepo：workspace: 'packages/*' 配合 glob。

适用场景

  • 为 npm 发布准备 TS/JS 库。
  • 需要生成 .d.ts 的库。
  • 需要同时输出 ESM 与 CJS（或 IIFE、UMD）的库。
  • 从 tsup 迁移的项目。
  • React、Vue、Solid、Svelte 组件库构建。
  • 需要 CSS、Sass 处理或 WASM 支持的库。
  • 需要打包为独立可执行文件的 CLI 工具。
  • Monorepo / workspace 多包构建。
  • 希望在上线前用 publint、attw 做包校验的 CI 流程。

限制与说明

  • CSS 处理与可执行文件打包在文档中标注为 experimental（实验性）。
  • CSS 处理需要额外安装 @tsdown/css；跨平台可执行文件需要 @tsdown/exe。
  • Svelte 组件库文档建议采用 source distribution 方式。
  • 具体收费、价格、平台覆盖与更多落地效果，资料中暂未提供。

资源

  • 文档：https://tsdown.dev
  • GitHub：https://github.com/rolldown/tsdown
  • Rolldown：https://rolldown.rs
  • 迁移指南：https://tsdown.dev/guide/migrate-from-tsup