开发React组件库：是否应将node modules纳入库打包？

核心背景 #

你开发的内部React组件库需要输出CommonJS（CJS）格式以兼容Next.js，但部分依赖（如swiper）仅支持ES Modules（ESM），导致兼容性冲突，以下是针对三个可选方案的具体分析和推荐：

方案1：依赖声明为peerDependencies #

• 优势：组件库体积大幅减小，不会重复打包依赖；业务项目可自主控制依赖版本，适配自身需求。
• 劣势：每个使用组件库的Next.js项目都需要额外配置——比如在next.config.js中添加transpilePackages指定需转译的依赖，Jest中调整transformIgnorePatterns避免测试报错。内部项目数量多的话，配置重复且易出现不一致问题，新人上手成本高。

方案2：依赖全打包+双格式输出 #

• 优势：业务项目无需任何额外配置，开箱即用；同时输出CJS和ESM格式，能兼容不同版本的Next.js（比如Next.js 13+对ESM支持更好，旧版本依赖CJS）。
• 劣势：组件库体积会明显增大，若业务项目本身已引入同一依赖，会出现重复打包的情况。虽然属于打包反模式，但内部场景下版本冲突风险可控，毕竟都是团队内部项目。

方案3：混合转译方案（仅处理不兼容依赖） #

• 优势：平衡体积和易用性，只打包不支持CJS的依赖，其他依赖仍设为external，避免不必要的体积膨胀；业务项目几乎无需额外配置。
• 劣势：需要维护一个「需转译依赖清单」，后续新增依赖时要逐一判断是否兼容CJS，长期维护有一定心智负担；打包工具（如Rollup、Vite）的配置会更复杂，需要区分哪些依赖要打包、哪些要排除。

推荐方案 #

根据内部项目的数量和团队维护成本，优先级排序如下：

1. 混合转译方案：如果内部项目数量≥3个，优先选这个。可以通过Rollup的external配置排除支持双格式的依赖，用@rollup/plugin-commonjs转译仅支持ESM的依赖，既控制了体积，又避免了业务项目的配置负担。
2. 双格式全打包方案：如果团队不想维护依赖清单，或者组件库依赖较少，这个方案最省心。内部网络下体积增大的影响有限，且可以通过tree-shaking优化冗余代码。
3. peerDependencies方案：仅适合内部项目数量≤2个的场景，否则配置维护成本会远超过体积优势带来的收益。如果选这个，可以同步维护一个内部Next.js模板，把必要的配置提前写好，降低项目配置成本。

内容的提问来源于stack exchange，提问作者Antoine Richard