近日笔者维护自己的几个无名小repo时,发觉想要创作一个第三方angular包,着实有一些不难但易乱的小问题,故作此文总结。本文将完成以下内容:
从空白开始搭建一个基于angular的第三方包
在本地测试待发布的包
在npm或yarn发布包中指定内容
在普通angular应用中引入并使用发布的包
基本项目搭建
一般的angular app使用angular-cli创建,直接ng new name搞定,生成的项目把webpack、AOT、dev server等细节都隐藏了,还支持各种参数来配置测试和sass等,使用起来直接npm run start、npm run build,可以说是非常傻瓜了,跳过了学习webpack等的许多大坑。
不过,如果是要搭建angular第三方包,预编译样式和打包部署这些一般就用不着了,取而代之的要熟悉npm(yarn)、tsconfig。
初始化
项目搭建命令如下:
mkdir my-ng-lib cd my-ng-lib yarn init
一路回车(实际情况中还是要编辑好包的基本信息)最终得到一个package.json,然后vscode打开:
初始化npm包
依赖
作为angular的第三方包,首先需要安装如下依赖:
依赖安装
其中typescript指定了版本是为了和当前angular-cli使用的版本保持一致,实际可能不必要这么做。
现在安装了开发时要用到的包,但这些包并不用在发布以后,实际上发布的时候我们想要的只是发布自己写的代码,而不是依赖的代码,这需要在package.json中配置peerDependencies作为前置依赖,但包本身不会实际安装这些依赖,实际的包应该由应用项目来安装。现在把peerDependencies添加进package.json:
"peerDependencies": { "@angular/common": ">=5.0.0", "@angular/core": ">=5.0.0", "rxjs": ">=5.0.0" }
项目编写
基本项目搭建好后,我们应该只有package.json、node_modules和一个lock文件在项目中,现在要加上真正的项目代码了。
无论这个包是用来实现什么目的的,作为一个第三方包,都应该要导出自己的功能以让其他项目引入使用,所以在项目根目录首先要有一个index.js文件,而我们要开发的是基于angular的TypeScript包,使用的自然是index.ts了,内容就是各种export导出类型、接口、方法等。作为示例这里只导出一个常量:
export const myNgLib: string = 'Hello, thie is my angular 3rd part lib';
为了支持TypeScript我们还需要一个tsconfig.json:
{ "compilerOptions": { "baseUrl": ".", // 基于哪个目录编译ts "declaration": true, // 是否生成声明文件即*.d.ts文件,有了它才有TS的代码提示 "experimentalDecorators": true, // 用于支持TS装饰器如angular中的 @NgModule({}) 之类 "emitDecoratorMetadata": true, // 用于支持TS装饰器如angular中的 @NgModule({}) 之类 "module": "commonjs", // 模块化形式 "moduleResolution": "node", // 模块化形式 "rootDir": ".", // 以哪个目录为根 "lib": ["es2015", "dom"], // 支持编译的内置库 "skipDefaultLibCheck": true, // 是否跳过内置库检查 "skipLibCheck": true, // 跳过库检查 "target": "es5", // 编译目标版本 "suppressImplicitAnyIndexErrors": true, // 几个检查代码的规则 "strictNullChecks": true, // 几个检查代码的规则 "noImplicitAny": true, // 几个检查代码的规则 "sourceMap": true, // 是否生成 .js.map "removeComments": true, // 移除注释 "noFallthroughCasesInSwitch": true // 几个检查代码的规则 }, "exclude": [ // 编译时排除以下内容 "node_modules", "*.d.ts", "**/*.d.ts" ] }
其中的规则各有各效果,有些为了确定编译路径,有些为了语法检查,有些为了输出声明,还有排除规则等,现在可以tsc看看效果了,不过要先把tsc添加到package.json的scripts中:
"scripts": { "tsc": "tsc" }
编译得到.js、js.map、.d.ts
发布
完美,这么厉害的包,接下来赶紧发布它。发布命令是
yarn publish
不过在此之前,要准备几件事:
npm账号
发布之前自然得先有npm账号,添加了就可以,最后用npm whoami确认身份。
包的基本信息
也就是要完善package.json,让全网知道这么厉害的包是我们开发的,包括开源许可、包名、作者、版本号等,最重要直接影响发布的是版本号。
选择性发布