ng-packagr中处理次级入口点的peerDependencies问题解析

背景介绍

在Angular库开发中，ng-packagr是一个非常重要的构建工具，它帮助开发者将Angular组件和库打包成符合Angular Package Format规范的格式。在实际开发中，我们经常会遇到需要将库拆分为多个次级入口点(secondary entry points)的情况，这时peerDependencies的处理就变得尤为重要。

问题现象

当开发者在次级入口点的package.json中声明peerDependencies时，发现构建后生成的package.json文件中这些peerDependencies信息丢失了。例如：

// 原始次级入口点package.json
{
    "name": "@foo/ngx-components/editor",
    "peerDependencies": {
        "angular/core": "^12.0.0",
        "monaco-editor": "0.45.0"
    }
}

// 构建后生成的package.json
{
  "module": "../fesm2022/foo-ngx-components-editor.mjs"
}

原因分析

这种行为实际上是ng-packagr的预期设计。在Angular库的打包规范中，peerDependencies应该只存在于主package.json中，而不是分散在各个次级入口点中。这是因为：

1. 依赖管理一致性：将所有peerDependencies集中在主package.json中可以确保整个库的依赖关系清晰一致
2. 安装行为：npm/yarn等包管理器在安装时只会查看主package.json的peerDependencies
3. 避免重复：防止同一个依赖在不同入口点被多次声明导致版本冲突

解决方案

正确的做法是将所有peerDependencies统一放在主package.json中，即使某些依赖只在特定次级入口点中使用。例如：

// 主package.json
{
  "name": "@foo/ngx-components",
  "peerDependencies": {
    "@angular/core": "^12.0.0",
    "monaco-editor": "0.45.0"
  }
}

最佳实践

1. 集中管理依赖：将所有peerDependencies放在主package.json中统一管理
2. 文档说明：在库文档中明确说明哪些次级入口点需要哪些额外依赖
3. 版本协调：确保所有入口点使用的peerDependencies版本一致
4. 构建验证：在CI流程中添加检查，确保构建产物符合预期

技术细节

ng-packagr在构建过程中会处理次级入口点的package.json，但会特意移除peerDependencies等信息，这是有意为之的设计决策。构建系统认为依赖关系应该由主包统一管理，而不是分散在各个入口点中。

总结

理解ng-packagr的这种设计理念对于开发高质量的Angular库非常重要。通过集中管理peerDependencies，可以确保库的依赖关系清晰、一致，避免潜在的问题。开发者应该适应这种模式，而不是试图在各个次级入口点中分散声明依赖关系。