叁叁肆

这个世界会好吗

453篇博客

编写一个供浏览器端使用的NPM包

叁叁肆2018-10-22 13:15

此文已由作者吴维伟授权网易云社区发布。

欢迎访问网易云社区,了解更多网易技术产品运营经验。


在编写程序时,总会有一些代码是我们不愿意一遍又一遍重复地去写的,比如一些UI或交互相似组件,或是一些相似的流程或逻辑。以前,面对这样的情况,我会将可以复用的部分抽象出来,做成可以复用的模块,放在专门存放公用模块的文件夹中,便于查找和引用。但是这样只能解决单个项目中公用模块复用的问题,如果你的模块需要被多个项目复用,那么就需要另寻它法了。本文讨论的是通过发布npm包来实现模块复用时有哪些注意事项。


新建一个包


在项目根目录下执行下面的命令,初始化package.json文件。


$ npm init

文件中各字段的含义可以参考官方文档。 其中需要注意的是:


  • name指定包名,在发布包时包名不能与已有包名重复。在发布前可以通过npm info packageName查看包名是否已存在。

  • main指定加载包时默认加载的文件。

  • files指定发布包时需要发布的文件。一般来说,.git, node_modules, test等文件不应该发布到npm仓库中。

  • dependencies指定需要依赖的第三方包。在安装此包时,这些第三方包也同时会被安装。为了提高包的安装速度,不必要的依赖不要放在dependencies中。


打包

为什么需要打包

业务项目的打包过程中,为了提高打包速度,某些处理过程会过滤第三方包,如babel。而且业务项目中可能没有处理第三方库中某些特性的能力,如第三方包中使用了coffeescript。所以作为一个能被良好复用的第三方包,需要在发布前,对自己的源码进行编译打包。


注意事项

可以选择webpack进行打包。在打包过程中,与业务项目不同的是:

将output.libraryTarget配置为commonjs

业务项目中打包后的文件只需要被执行,并不需要对外导出变量。为了能够以commonjs规范对外导出变量,需要将output.libraryTarget配置为commonjs点击查看如何配置

打包时过滤第三方包

作为一个NPM包,可能会依赖一些第三方包,如React。如果直接进行打包,打包后的文件会包含React的代码。一般依赖这个NPM包的业务项目也会依赖React,所以最终React的代码会被打包两次。所以建议在打包时对第三方包进行过滤,并把用到的第三方包声明在dependencies中,使依赖的第三方包随业务项目一起打包。 点击查看如何过滤第三方包

使用babel-plugin-transform-runtime

我们通常会使用babel来编译代码。在编译的过程中,babel会额外注入一些代码,使编译后的代码有更好的兼容性,如继承,Promise, Map, Set等功能的实现。为了防止这些额外的代码被重复加入,可以在编译时使用babel-plugin-transform-runtime插件,使这些额外的功能从第三方包(babel-runtime)中导入,而不是直接添加实现代码。同时在打包时也要对babel-runtime进行过滤,使babel-runtime随业务项目一起打包。 点击查看如何使用transform-runtime


按需加载

有时一个NPM包会提供很多功能,而依赖它的业务项目只需要其中一部分。这个时候,NPM包需要提供按需加载的功能,即在打包时只会将引用的部分模块打包进来,从而减少打包后文件的体积。

babel-plugin-import的使用

babel-plugin-import插件可以实现按需加载的功能。


{
    "plugins": [
        ["import", {
            "libraryName": "abc",
            "style": true
        }]
    ]}

上面的代码是babel配置文件的一部分,声明对abc模块使用按需加载的功能。它对下面的一段代码进行编译:


// 从模块中导入var1, var2, var3 3个变量,只使用了var1import {var1, var2, var3} from 'abc'console.log(var1)

编译结果:


import { style as _style } from 'abc/lib/var1/style';import _default from 'abc/lib/var1';

console.log(_default);

编译前,导入整个abc包。编译后,只导入了使用了的var1。babel-plugin-import支持更灵活的配置,点击查看详情。 点击查看如何配置babel


为了使babel-plugin-import能够按需加载我们的NPM包,在打包时需要有一些相应的配置。如上面的abc包,需要对var1, var2, var3等模块分别打包。所以打包后的文件除了abc/index.js外,还需要有abc/lib/var1/index.js, abc/lib/var1/style.js等


测试

对于一个公用模块,最重要的应该是它的稳定性。一个每次升级都可能带来新bug的公用模块并不是我们想要的。相比于业务项目,公用模块提供的功能变化较小,这样单元测试就有了用武之地。想象之中,公用模块的迭代过程是这样的:


  • 明确模块提供的功能,并针对这些功能编写测试用例。

  • 进行功能开发,通过测试用例。

  • 如果需要修复bug或新增功能,针对bug或新功能编写测试用例,通过用例。

    如何进行单元测试

    断言库

    断言库主要用于对数据进行比较,判断其是否与预期相符。对于不满足预期的断言,会抛出一个异常.

    assert.equal('a', 'b')

    如上面的断言会抛出一个异常AssertionError: 'a' == 'b'断言库推荐使用Chai,支持多种风格的断言。

    测试框架

    测试框架可以对测试用例进行分类管理。每一个测试用例在一个单独的闭包中执行,如果在这个闭包中捕获到异常,则认为这个测试用例没有通过。


// 一个分类describe('type1:', function () {    // 一个用例(通过)
    it('case 1:', function () {
        assert.equal('a', 'a')
    })   // 一个用例(未通过)
    it('case 2:', function () {
        assert.equal('a', 'b')
    })
})

测试框架推荐使用mocha


测试执行器

推荐使用karma,它可以集成webpack、 mocha、 chai、 浏览器,对测试代码进行打包,并在浏览器环境下执行测试用例,最后在控制台输出结果。


文档

一个公用模块应该有一个API文档,但是手动维护一个文档的成本过高。所幸现在有一些工具可以根据代码中的注释自动生成API文档,你需要做的只是根据规范添加代码注释。 点击查看注释规范生成网页形式的文档生成markdown形式的文档


网易云免费体验馆,0成本体验20+款云产品! 

更多网易技术、产品、运营经验分享请点击


相关文章:
【推荐】 为什么我打的jar包没有注解?
【推荐】 如何让你产品的用户拥有一流的上传体验