angular第三方包开发整理(小结)


Posted in Javascript onApril 19, 2018

近日笔者维护自己的几个无名小repo时,发觉想要创作一个第三方angular包,着实有一些不难但易乱的小问题,故作此文总结。本文将完成以下内容:

  1. 从空白开始搭建一个基于angular的第三方包
  2. 在本地测试待发布的包
  3. 在npm或yarn发布包中指定内容
  4. 在普通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打开:

angular第三方包开发整理(小结)

初始化npm包

依赖

作为angular的第三方包,首先需要安装如下依赖:

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"
 }

angular第三方包开发整理(小结)

编译得到.js、js.map、.d.ts

发布

完美,这么厉害的包,接下来赶紧发布它。发布命令是

yarn publish

不过在此之前,要准备几件事:

npm账号

发布之前自然得先有npm账号,添加了就可以,最后用npm whoami确认身份。

包的基本信息

也就是要完善package.json,让全网知道这么厉害的包是我们开发的,包括开源许可、包名、作者、版本号等,最重要直接影响发布的是版本号。

选择性发布

基于angular的第三方包区别与普通的js包最大的地方就在于,不能直接把整个包都发布到npm,这样会导致奇怪错误,原因在于.ts文件,实际上需要发布的只是.js、.js.map、.d.ts这三种类型的文件就够了。

因为在其他项目中不一定会使用TypeScript,即使用了也不会刻意包含node_modules目录,也就是说其他项目只管使用,编译的活由我们得包自己来做,相反要是我们还发布多余的.ts文件,只会导致错误。

为了做到选择性发布,需要一个.npmignore文件,和.gitignore配合用来忽略上传的文件,一般这些编译输出我们会添加在.gitignore中,若项目不存在.npmignore,发布到npm时也会使用.gitignore,这不是我们想要的,所以需要再创建这个.npmignore来忽略.ts文件而包含编译输出:

node_modules
yarn-error.log
tsconfig.json
.gitignore
.npmignore
yarn.lock
*.ts
!*.d.ts

现在我们的项目看起来是这样的:

angular第三方包开发整理(小结)

待发布项目

使用yarn pack命令得到本地打包看看效果如何:

angular第三方包开发整理(小结)

本地打包

看起来非常完美,该有的都有了,不该有的都忽略了,那就可以发布了,不过这里就不发布这个没什么用处的包了 : )
打包至此完成,现在看看用起来怎么样。

本地测试

angular的第三方包要做本地测试的话,与普通的包比有一点不足,就是用不了npm link,这会导致错误,特别是在第三方包使用到依赖注入的情况下,原因是运行时实际是在两个angular环境下,再进一步说是因为第三方包依赖的是自己的node_modules,解决办法也很粗暴,删掉第三方包的node_modules即可,不过这代价显然有点大。找遍GitHub发现的另一个办法是配合--preserve-symlinks参数,不过可能是笔者使用姿势不对一直没效果。

最后笔者自己的曲线救国办法是手动写package.json的scripts,本地测试步骤是:

  1. 执行 yarn pack得到本地打包
  2. 解压到测试项目的node_modules中假装是安装的项目
  3. 测试项目中像使用普通安装包一样使用这个直接复制进来的包

参考脚本如下:

"scripts": {
  "prepublish": "npm run clean && tsc", // 清理并编译
  "clean": "rimraf index.js index.js.map index.d.ts src/**/*.js src/**/*.js.map src/**/*.d.ts linktest.tgz", // 清理编译文件
  "link": "npm run pack && tar -zxf linktest.tgz && rimraf ../lib-test-app/node_modules/my-ng-lib && mv package ../lib-test-app/node_modules/my-ng-lib", // 打包后解压并移动到测试项目node_modules中
  "pack": "npm run prepublish && yarn pack --filename linktest.tgz" // 执行编译并打包
 }

总结

  1. 发布基于angular的第三方包的两个难点:一是如何处理好TypeScript的编译,二是如何处理好angular运行上下文。
  2. 本文的命令均使用yarn完成,npm版本命令大同小异均有其对应命令,且发布的包都是在npm托管。
  3. 另外本文仅涉及发布最基本的基于angular的第三方包,包的实际功能方面没有做深入。其实对于不同功能的第三方包,仍有需要学习的内容。

参考资料:

How to create an Angular component library, and how to consume it using SystemJs or Webpack
stories linked library
npm link doesn't work with 1.5.4 version

以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持三水点靠木。

Javascript 相关文章推荐
jQuery EasyUI API 中文文档 - ComboGrid 组合表格
Oct 13 Javascript
jquery中dom操作和事件的实例学习-表单验证
Nov 30 Javascript
js几秒以后倒计时跳转示例
Dec 26 Javascript
js实现时间显示几天前、几小时前或者几分钟前的方法集锦
May 29 Javascript
深入分析javascript中的错误处理机制
Jul 17 Javascript
前端程序员必须知道的高性能Javascript知识
Aug 24 Javascript
AngularJS指令与控制器之间的交互功能示例
Dec 14 Javascript
node koa2实现上传图片并且同步上传到七牛云存储
Jul 31 Javascript
bootstrap 通过加减按钮实现输入框组功能
Nov 15 Javascript
javascript开发实现贪吃蛇游戏
Jul 31 Javascript
vue使用echarts实现水平柱形图实例
Sep 09 Javascript
JavaScript使用canvas绘制坐标和线
Apr 28 Javascript
如何从零开始利用js手写一个Promise库详解
Apr 19 #Javascript
30分钟快速入门掌握ES6/ES2015的核心内容(下)
Apr 18 #Javascript
30分钟快速入门掌握ES6/ES2015的核心内容(上)
Apr 18 #Javascript
原生js实现拖拽功能基本思路详解
Apr 18 #Javascript
一个基于react的图片裁剪组件示例
Apr 18 #Javascript
JS实现对json对象排序并删除id相同项功能示例
Apr 18 #Javascript
Angular ng-animate和ng-cookies用法详解
Apr 18 #Javascript
You might like
法兰绒滤网冲泡
2021/03/03 冲泡冲煮
中篇:安装及配置PHP
2006/12/13 PHP
推荐几个开源的微信开发项目
2014/12/28 PHP
JSON用法之将PHP数组转JS数组,JS如何接收PHP数组
2015/10/08 PHP
Yii框架操作cookie与session的方法实例详解
2019/09/04 PHP
Extjs Ajax 乱码问题解决方案
2009/04/15 Javascript
javascript document.referrer 用法
2009/04/30 Javascript
javascript 三种编解码方式
2010/02/01 Javascript
angularjs中的e2e测试实例
2014/12/06 Javascript
Javascript中的包装类型介绍
2015/04/02 Javascript
AngularJS基础 ng-keyup 指令简单示例
2016/08/02 Javascript
纯js实现画一棵树的示例
2017/09/05 Javascript
jQuery实现用户信息表格的添加和删除功能
2017/09/12 jQuery
浅谈 vue 中的 watcher
2017/12/04 Javascript
JavaScript寄生组合式继承实例详解
2018/01/06 Javascript
Vue封装Swiper实现图片轮播效果
2018/02/06 Javascript
JS引用传递与值传递的区别与用法分析
2018/06/01 Javascript
layui问题之模拟select点击事件的实例讲解
2018/08/15 Javascript
swiper在vue项目中loop循环轮播失效的解决方法
2018/09/15 Javascript
详解项目升级到vue-cli3的正确姿势
2019/01/28 Javascript
微信小程序按顺序同步执行的两种方式
2019/12/20 Javascript
解决VUE项目使用Element-ui 下拉组件的验证失效问题
2020/11/07 Javascript
[05:15]DOTA2英雄梦之声_第16期_灰烬之灵
2014/06/21 DOTA
Python中列表的一些基本操作知识汇总
2015/05/20 Python
Python使用base64模块进行二进制数据编码详解
2018/01/11 Python
python实现音乐下载器
2018/04/15 Python
python web框架Flask实现图形验证码及验证码的动态刷新实例
2019/10/14 Python
python+flask编写一个简单的登录接口
2020/11/13 Python
python中pivot()函数基础知识点
2021/01/03 Python
详解如何修改jupyter notebook的默认目录和默认浏览器
2021/01/24 Python
澳大利亚第一的设计师礼服租赁网站:GlamCorner
2017/08/13 全球购物
我爱幼儿园演讲稿
2014/09/11 职场文书
离婚纠纷代理词
2015/05/23 职场文书
会计试用期工作总结2015
2015/05/28 职场文书
新员工试用期工作总结2015
2015/05/28 职场文书
pygame面向对象的飞行小鸟实现(Flappy bird)
2021/04/01 Python