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

在编写程序时，总会有一些代码是我们不愿意一遍又一遍重复地去写的，比如一些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个变量，只使用了var1
import {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形式的文档