使用 ng-packagr 打包 Angular

写在前面

为了让 Angular 类库应用范围更自由，Angular 提出一套打包格式建议名曰：Angular Package Format，包括 FESM201五、FESM五、UMD、ESM201五、ESM五、ES2015 格式，不一样格式能够在不一样的环境（Angular Cli、Webpack、SystemJS等）中使用。

传统方式须要对这些格式逐一打包，一个示例打包脚本写法。这种写法只能针对不一样项目的配置，并且除非你了解这些格式的本质不然很难维护；后来社区根据 APF 规范实现了类库 ng-packagr，经过简单的配置能够将你的类库打包成 APF 规范格式。

至 V6 之后 Angular Cli 也基于 ng-packagr 实现了另外一个 @angular-devkit/build-ng-packagr 应用构建器。

如何使用

既然 ng-packagr 被 Angular Cli 内置，这让咱们进一步简化了生产一个 APF 规范格式的类库的成本。在 Angualr Cli 里使用 ng g library 来建立一个类库模板，例如在一个新的 Angular 应用里执行：

ng g library <library name>

而打包，则：

ng build <library name>

最终，将生成的 dist/<libary name> 目录下文件上传相应包管理服务器（例如：npm）提供给其余 人使用。

配置说明

由 Angular Cli 生成的类库模板大部份内容同 Angular 应用同样，只是多了一个 ng-package.json 的配置文件（对于生产环境是 ng-package.prod.json），它是专门针对 ng-packagr 的一个配置文件，如同 angular.json 通常也是基于 JSON Schema 格式，所以能够经过访问 ng-package.schema.json 了解全部细节，如下描述一些重点项。

whitelistedNonPeerDependencies

ng-packagr 默认会根据 package.json 的 peerDependencies 节点清单来决定类库所须要第三方依赖包，这些依赖包是不会被打包至类库。

然而，所依赖包不存在 peerDependencies 节点里时（固然建议须要依赖的项应该在里面），就须要该属性的配置。

lib/entryFile

指定入口文件。

lib/umdModuleIds

UMD 格式采用 rollup 打包，当类库须要引用一些没法猜出正确 UMD 标识符时，就须要你手动映射这些类库的标识。

"umdModuleIds": {
    "lodash": "_"
}

angular.json

Angular Cli 配置文件 angular.json 内会增长一个以 <libary name> 命名的构建配置，绝大多数配置性同普通 Angular 应用一模一样，惟一不一样的是 builder 节点为：

"builder": "@angular-devkit/build-ng-packagr:build"

次级入口

有时候一个类库可能会包含着多个二次入口，就像 @angular/core 类库包含着一个 @angular/core/testing 模块，它只是运用于测试，所以并不但愿在项目中引入 @angular/core 时也包含测试代码，但同时两者又是同一个功能性时，这种次级导入显得很是重要。

另外一种像 ngx-bootstrap、@angular/cdk/ally 等都提供次级模块的导入，能够更好的优化体积。

不论出于何种目的，均可以经过 Angular Cli 简单的文件组织进一步打包出主、次级分明的类库。

ng g library 生成的结构大概以下：

<libary name>
├── src
|   ├── public_api.ts
|   └── lib/*.ts
├── ng-package.json
├── ng-package.prod.json
├── package.json
├── tsconfig.lib.json
└── tsconfig.spec.json

当根目录下包含 README.md、 LICENSE 时会自动被复制到 dist 目录中，Npm 规定必须包含 README.md 文件，不然访问已发布类库页时会有未找到描述文件错误提示。

若想建立一个 <libary name>/testing 的次级入口，只须要在 <libary name> 根目录下建立一个 testing 目录：

<libary name>
├── src
|   ├── public_api.ts
|   └── lib/*.ts
├── ng-package.json
├── ng-package.prod.json
├── package.json
├── tsconfig.lib.json
├── tsconfig.spec.json
└── testing
    ├── src
    |   ├── public_api.ts
    |   └── *.ts
    └── package.json

核心是须要提供一个 package.json 文件，并且内容简单到姥姥家。

{
    "ngPackage": {}
}

最后，依然使用 ng build <libary name>，会产生一个次级导入模块。

小结

至此，基本上利用 Angular Cli 能够快速的构建一个可发布于 Npm Angular 类库，更复杂的能够构建像 ngx-bootstrap、@angular/cdk/* 类库。

自定义构建

Angular Cli 虽然提供很是便利的环境，可是对于一些复杂环境像 Delon 类库（ng-alain基建系列类库）包含着多个类库、类库又包含多个次级导入时，Angular Cli 会显得有点啰嗦，特别是对每一个类库的 angular.json 配置。其实 @angular-devkit/build-ng-packagr 很是简单，若是将取进一步简化，整个实现差很少至关于：

const path = require('path');
const ngPackage = require('ng-packagr');

const target = path.resolve(__dirname, './projects/<libary name>');

ngPackage
  .ngPackagr()
  .forProject(path.resolve(target, `ng-package.prod.json`))
  .withTsConfig(path.resolve(target, 'tsconfig.lib.json'))
  .build()
  .then(() => {
      // 构建完成后干点事
  });

将上面的代码放到 ./build.js，执行：

node scripts/build.js

其结果完成是等价。

build() 返回的是一个 Promise 对象，意味着能够确保构建开始前和结束后作一点额外的事。

总结

ng-packagr 极大简化 Angular 类库被打包出一个 APF 规范建议，虽然它以 ng- 开头，但本质上并不必定非要在 Angular 中运用，也可使用在 React、VUE。