对等依赖与树摇

对等依赖声明您的库所需、但期望由使用者提供的包。在您的库的 package.json 中，应将 React 放在 peerDependencies 中，而不是 dependencies 中。用户安装您的库时，npm/yarn 不会自动安装 React——用户的应用已经拥有 React，您的库会与应用共享该实例。

如果将 React 放入您库的 dependencies 中，npm 可能会在使用者的 React 旁边再安装一份 React。同一个应用中的两个 React 实例会因“无效的钩子调用”错误而破坏所有钩子。将 React 声明为 peerDependency，就是告诉 npm：“我需要 React，但请使用使用者已经拥有的那一份。”

某些对等依赖可能是可选的——例如，同时支持 styled-components 和 CSS Modules 的库。使用 peerDependenciesMeta 标记可选对等依赖：{ 'styled-components': { optional: true } }。npm 不会因缺少可选对等依赖而向用户发出警告，但安装可选包后仍然可以提供 TypeScript 类型。

package.json 中的 sideEffects 字段会告诉打包工具您的库是否可以安全地进行摇树优化。设置 "sideEffects": false 后，webpack、Rollup 及类似工具会认为从您的库中导入任何模块都不会产生副作用，因此可以安全地从使用者的包中删除所有未使用的导出内容。

CSS 导入是一种常见的副作用——导入 CSS 会将样式注入页面。如果您的库导入 CSS 文件，请设置 "sideEffects": ["*.css", "*.scss"]，告诉打包工具 JS 文件可以安全地进行摇树优化，但导入 CSS 文件时必须始终包含它们。

要最大限度地实现摇树优化，请从各自的文件中将每个组件作为命名导出。在您的 index.ts 中重新导出所有内容：export { Button } from './Button'。当使用者只导入 Button 时，打包工具可以删除其他所有组件。通过重新导出实现的集中导出文件可以启用这种模式。

使用 bundlejs.com 测试摇树优化：粘贴您的导入语句后，它会报告实际的包大小。size-limit npm 包可以让您在 package.json 中定义大小预算，并在导入大小超过限制时使 CI 失败："size-limit": [{ "path": "dist/index.js", "limit": "10 KB" }]。

为库的导入建立大小预算。在持续集成中运行 npx size-limit 以执行该预算。如果包的影响范围随时间扩大，说明范围正在蔓延。专注的组件库应将单个组件的导入大小控制在几 KB 以内。在回归影响使用者之前发出警报。

如果您打算分发组件库，请避免使用 styled-components 和 Emotion。这些运行时 CSS-in-JS 方案要求使用者安装相同的库和版本，从而造成对等依赖冲突。即使使用者采用 Tailwind 或普通 CSS，他们仍然必须将 CSS-in-JS 运行时打包。请优先使用在构建时编译为普通 CSS 的 CSS Modules。

将 CSS Modules 与能够处理它们的打包工具结合使用时，它们非常适合库。tsup 和 Rollup 可以将 CSS Modules 输出内联为带作用域的类名。使用者无需进行任何配置——样式已经限定了作用域，并包含在 JS 包中，或作为导入的独立 CSS 文件存在。

您自己的开发工具（tsup、TypeScript、测试库、Storybook）应放在 devDependencies 中——它们只在开发期间需要，使用者执行 npm install 时不会安装这些工具。React 同时放在 peerDependencies（运行时要求）和 devDependencies（在本地编译和测试库所需）中。

在库的 package.json 中设置 "sideEffects": false 会向打包工具传达什么信息？

将 React 声明在 peerDependencies（而不是 dependencies）中，让使用者与其应用共享同一个 React 实例。sideEffects: false 可以对您的库进行完整的摇树优化。使用 sideEffects: ['*.css'] 防止 CSS 导入被删除。从单独文件中进行命名导出，可以最大限度地提高摇树优化粒度。在持续集成中使用 size-limit 执行大小预算。在库中优先使用 CSS Modules，而不是 CSS-in-JS，以避免对等依赖冲突。