使用 Rollup 和 tsup 为库打包

Vite 的默认配置针对应用进行了优化——它会打包所有内容、处理资源并生成 index.html。组件库需要不同的输出：纯 ESM/CJS JavaScript 文件、不产生运行时开销、不捆绑 React，并提供正确的 TypeScript 声明。Vite 库模式可以使用，但 Rollup 和 tsup 更适合这一用途。

多年来，Rollup 一直是 JavaScript 库的标准打包工具。它能生成整洁、高效的输出，具备出色的摇树优化，并支持 ESM 和 CJS 两种输出格式。Rollup 的作用域提升消除了模块包装器开销，从而生成尽可能小的库包。

tsup 是由 esbuild 驱动的零配置 TypeScript 打包工具。它比 Rollup 快得多（esbuild 以微秒而非毫秒完成编译）。最简配置：{ entry: ['src/index.ts'], format: ['esm', 'cjs'], dts: true } 会自动生成两种模块格式和 TypeScript 声明。

tsup 的核心选项包括：入口是入口文件数组。格式指定输出格式：['esm', 'cjs']。dts: true 会在 JS 输出旁生成 .d.ts TypeScript 声明文件。目标设置最低 JavaScript 环境（esnext 或 es2020）。拆分：false会将输出保留在单个文件中。

esbuild（通过 tsup）比 Rollup 的编译速度快 10 到 100 倍。Rollup 生成的输出略微更加优化，摇树优化粒度更细，并且能更好地控制代码块边界。对于大多数组件库来说，tsup 的速度在开发阶段更具优势。如果需要最大程度地控制摇树优化，或需要处理复杂的多入口设置，则更适合使用 Rollup。

React 库最关键的打包工具配置是：绝不要将 React 或 ReactDOM 打包。将它们标记为外部依赖，使其从输出中排除。如果您的库打包了 React，使用者最终会得到两份 React——一份来自您的包，另一份来自其应用。这会由于存在多个 React 实例而破坏所有 React 钩子。

在 tsup 配置中，使用 external 选项：external: ['react', 'react-dom']。在 Rollup 配置中，设置 external: ['react', 'react-dom', 'react/jsx-runtime']。如果您的库使用 JSX 转换，请包含 react/jsx-runtime。此外，也要将库声明的其他对等依赖标记为外部依赖。

TypeScript 库的最小 Rollup 配置需要三个插件：用于 TypeScript 编译的 @rollup/plugin-typescript、用于解析 node_modules 导入的 @rollup/plugin-node-resolve，以及用于将 CommonJS 依赖转换为 ESM 以打包的 @rollup/plugin-commonjs。添加 rollup-plugin-dts 以生成声明文件。

典型的双格式库输出包括：面向 ESM 使用者的 dist/esm/index.js 和 dist/esm/index.d.ts，以及面向 CJS 使用者的 dist/cjs/index.js 和 dist/cjs/index.cjs。package.json 中的 exports 字段会将这些路径映射到正确的环境。TypeScript 类型声明文件与对应的 JS 文件并列存放。

大型库可以通过多个入口点让使用者只导入所需内容。例如：entry: ['src/index.ts', 'src/utils.ts', 'src/hooks.ts']。每个入口都会获得自己的输出文件。package.json 中的 exports 字段会将每个公共路径映射到对应输出：'./utils' → './dist/utils.js'。

将构建命令添加到 package.json 的脚本中："build": "tsup"。tsup 会从根目录中的 tsup.config.ts 读取配置。预发布脚本应运行构建命令："prepublishOnly": "npm run build" 可确保您的包在发布到 npm 前始终完成构建。

tsup（由 esbuild 驱动）提供快速的零配置打包，并支持 format: ['esm', 'cjs'] 和 dts: true。Rollup 通过 @rollup/plugin-typescript 提供更细粒度的摇树优化控制。关键规则是：始终将 react、react-dom 和所有对等依赖标记为外部依赖，避免将它们打包。输出到 dist/esm/ 和 dist/cjs/，并为其分别生成 TypeScript 声明文件。多个入口点可以让使用者进行更细粒度的摇树优化。