3-13 构建 Npm 模块

认识 Npm

Npm 是目前最大的 JavaScript 模块仓库，里面有来自全世界开发者上传的可复用模块。 虽然大多数情况下你都是这些开放模块的使用者，但有时候你也许会成为贡献者，开发一个模块上传到 Npm 仓库。

发布到 Npm 仓库的模块有以下几个特点：

• 每个模块根目录下都必须有一个描述该模块的 package.json 文件。该文件描述了模块的入口文件是哪个，该模块又依赖哪些模块等。想深入了解可以阅读文章 package.json文件。
• 模块中的文件以 JavaScript 文件为主，但不限于 JavaScript 文件。例如一个 UI 组件模块可能同时需要 JavaScript、CSS、图片文件等。
• 模块中的代码大多采用模块化规范，因为你的这个模块可能依赖其它模块，而且别的模块又可能依赖你的这个模块。因为目前支持比较广泛的是 CommonJS 模块化规范，上传到 Npm 仓库的代码最好遵守该规范。

抛出问题

Webpack 不仅可用于构建运行的应用，也可用于构建上传到 Npm 的模块。 接下来用教大家如何用 Webpack 构建一个可上传的 Npm 仓库的 React 组件，具体要求如下：

1. 源代码采用 ES6 写，但发布到 Npm 仓库的需要是 ES5 的，并且遵守 CommonJS 模块化规范。如果发布到 Npm 上去的 ES5 代码是经过转换的，请同时提供 Source Map 以方便调试。
2. 该 UI 组件依赖的其它资源文件例如 CSS 文件也需要包含在发布的模块里。
3. 尽量减少冗余代码，减少发布出去的组件的代码文件大小。
4. 发布出去的组件的代码中不能含有其依赖的模块的代码，而是让用户可选择性的去安装。例如不能内嵌 React 库的代码，这样做的目的是在其它组件也依赖 React 库时，防止 React 库的代码被重复打包。

在开始前先看下最终发布到 Npm 仓库的模块的目录结构：

node_modules/hello-webpack
├── lib
│   ├── index.css (组件所有依赖的 CSS 都在这个文件中)
│   ├── index.css.map
│   ├── index.js (符合 CommonJS 模块化规范的 ES5 代码)
│   └── index.js.map
├── src (ES6 源码)
│   ├── index.css
│   └── index.js
└── package.json (模块描述文件)

由于本节的重点不在于 React 而在于 Webpack，所以写一个最简单的 React 组件，其代码放在 src/index.js 文件中，内容如下：

import React, { Component } from 'react';
import './index.css';

// 导出该组件供给其它模块使用
export default class HelloWebpack extends Component {
  render() {
    return <h1 className="hello-component">Hello,Webpack</h1>
  }
}

要使用该模块时只需要这样：

// 通过 ES6 语法导入
import HelloWebpack from 'hello-webpack';
import 'hello-webpack/lib/index.css';

// 或者通过 ES5 语法导入
var HelloWebpack = require('hello-webpack');
require('hello-webpack/lib/index.css');

// 使用 react-dom 渲染
render(<HelloWebpack/>);

使用 Webpack 构建 Npm 模块

接下来用 Webpack 一条条来解决上面抛出问题的4点要求。

对于要求1，可以这样做到：

• 使用 babel-loader 把 ES6 代码转换成 ES5 的代码。
• 通过开启 devtool: 'source-map' 输出 Source Map 以发布调试。
• 设置 output.libraryTarget='commonjs2' 使输出的代码符合CommonJS2 模块化规范，以供给其它模块导入使用。在2-2 Output-libraryTarget 和 library 有介绍这个配置的含义。

相关的 Webpack 配置代码如下：

module.exports = {
  output: {
    // 输出的代码符合 CommonJS 模块化规范，以供给其它模块导入使用。
    libraryTarget: 'commonjs2',
  },
  // 输出 Source Map
  devtool: 'source-map',
};

对于要求2，需要通过 css-loader 和 extract-text-webpack-plugin 实现，相关的 Webpack 配置代码如下：

const ExtractTextPlugin = require('extract-text-webpack-plugin');

module.exports = {
  module: {
    rules: [
      {
        // 增加对 CSS 文件的支持
        test: /\.css/,
        // 提取出 Chunk 中的 CSS 代码到单独的文件中
        use: ExtractTextPlugin.extract({
          use: ['css-loader']
        }),
      },
    ]
  },
  plugins: [
    new ExtractTextPlugin({
      // 输出的 CSS 文件名称
      filename: 'index.css',
    }),
  ],
};

此步引入了3个新依赖：

# 安装 Webpack 构建所需要的新依赖
npm i -D style-loader css-loader extract-text-webpack-plugin

对于要求3，需要注意的是 Babel 在把 ES6 代码转换成 ES5 代码时会注入一些辅助函数。

例如下面这段 ES6 代码

class HelloWebpack extends Component{
}

在被转换成能正常运行的 ES5 代码时需要以下2个辅助函数：

• babel-runtime/helpers/createClass 用于实现 class 语法
• babel-runtime/helpers/inherits 用于实现 extends 语法

默认的情况下 Babel 会在每个输出文件中内嵌这些依赖的辅助函数的代码，如果多个源代码文件都依赖这些辅助函数，那么这些辅助函数的代码将会重复的出现很多次，造成代码冗余。 为了不让这些辅助函数的代重复出现，可以在依赖它们的时候通过 require('babel-runtime/helpers/createClass') 的方式去导入，这样就能做到只让它们出现一次。 babel-plugin-transform-runtime 插件就是用来做这个事情的。

修改 .babelrc 文件，为其加入 transform-runtime 插件：

{
  "plugins": [
    [
      "transform-runtime",
      {
        // transform-runtime 默认会自动的为你使用的 ES6 API 注入 polyfill
        // 假如你在源码中使用了 Promise，输出的代码将会自动注入 require('babel-runtime/core-js/Promise') 语句
        // polyfill 的注入应该交给模块使用者，因为使用者可能在其它地方已经注入了其它的 Promise polyfill 库
        // 所以关闭该功能
        "polyfill": false
      }
    ]
  ]
}

由于加入 babel-plugin-transform-runtime 后生成的代码中会大量出现类似 require('babel-runtime/helpers/createClass') 这样的语句，所以输出的代码将依赖 babel-runtime 模块。

此步引入了3个新依赖：

# 安装 Webpack 构建所需要的新依赖
npm i -D babel-plugin-transform-runtime
# 安装输出代码运行时所需的新依赖
npm i -S babel-runtime

对于要求4，需要通过在 2-7其它配置项 中介绍过的 Externals 来实现。

Externals 用来告诉 Webpack 要构建的代码中使用了哪些不用被打包的模块，也就是说这些模版是外部环境提供的，Webpack 在打包时可以忽略它们。

相关的 Webpack 配置代码如下：

module.exports = {
  // 通过正则命中所有以 react 或者 babel-runtime 开头的模块
  // 这些模块通过注册在运行环境中的全局变量访问，不用被重复打包进输出的代码里
  externals: /^(react|babel-runtime)/,
};

开启以上配置后，输出的代码中会存在导入 react 或者 babel-runtime 模块的代码，但是它们的 react 或者 babel-runtime 的内容不会被包含进去，如下：

[
    (function (module, exports) {
        module.exports = require("babel-runtime/helpers/inherits");
    }),
    (function (module, exports) {
        module.exports = require("react");
    })
]

这样就做到了在保持代码正确性的情况下，输出文件不存放 react 或者 babel-runtime 模块的代码。

实际上当你在开发 Npm 模块时，不只需要对 react 和 babel-runtime 模块做这样的处理，而是需要对所有正在开发的模块所依赖的模块进行这样的处理。 因为正在开发的模块所依赖的模块也可能被其它模块所依赖。 当一个项目中一个模块被依赖多次时，Webpack 只会将其打包一次，想更深入的了解可以阅读 5-2 输出文件分析。

完成以上4步后最终的 Webpack 完整配置代码如下：

const path = require('path');
const ExtractTextPlugin = require('extract-text-webpack-plugin');

module.exports = {
  // 模块的入口文件
  entry: './src/index.js',
  output: {
    // 输出文件的名称
    filename: 'index.js',
    // 输出文件的存放目录
    path: path.resolve(__dirname, 'lib'),
    // 输出的代码符合 CommonJS 模块化规范，以供给其它模块导入使用。
    libraryTarget: 'commonjs2',
  },
  // 通过正则命中所有以 react 或者 babel-runtime 开头的模块，
  // 这些模块使用外部的，不能被打包进输出的代码里，防止它们出现多次。
  externals: /^(react|babel-runtime)/,
  module: {
    rules: [
      {
        test: /\.js$/,
        use: ['babel-loader'],
        // 排除 node_modules 目录下的文件，
        // node_modules 目录下的文件都是采用的 ES5 语法，没必要再通过 Babel 去转换。
        exclude: path.resolve(__dirname, 'node_modules'),
      },
      {
        // 增加对 CSS 文件的支持
        test: /\.css/,
        // 提取出 Chunk 中的 CSS 代码到单独的文件中
        use: ExtractTextPlugin.extract({
          use: ['css-loader']
        }),
      },
    ]
  },
  plugins: [
    new ExtractTextPlugin({
      // 输出的 CSS 文件名称
      filename: 'index.css',
    }),
  ],
  // 输出 Source Map
  devtool: 'source-map',
};

重新执行构建后，你将会在项目目录下看到一个新目录 lib，里面放着要发布到 Npm 仓库的最终代码。

发布到 Npm

在把构建出的代码发布到 Npm 仓库前，还需要确保你的模块描述文件 package.json 是正确配置的。

由于构建出的代码的入口文件是 ./lib/index.js，需要修改 package.json 中的 main 字段如下：

{
  "main": "lib/index.js",
  "jsnext:main": "src/index.js"
}

其中 jsnext:main 字段用于指出采用 ES6 编写的模块入口文件所在的位置，这样做的目的是为了方便实现在 4-10 中介绍的 Tree Shaking。

修改完毕后在项目目录下执行 npm publish 就能把构建出的代码发布到 Npm 仓库中(确保已经 npm login 过)。

如果你想让发布到 Npm 上去的代码保持和源码的目录结构一致，那么用 Webpack 将不在适合。 因为源码是一个个分割的模块化文件，而 Webpack 会把这些模块组合在一起。 虽然 Webpack 输出的文件也可以是采用 CommonJS 模块化语法的，但在有些场景下把所有模块打包成一个文件发布到 Npm 是不适合的。 例如像 Lodash 这样的工具函数库在项目中可能只用到了其中几个工具函数，如果所有工具函数打包在一个文件中，那么所有工具函数都会被打包进去，而保持模块文件的独立能做到只打包进使用到的。 还有就是像 UI 组件库这样由大量独立组件组成的库也和 Lodash 类似。

所以 Webpack 适合于构建完整不可分割的 Npm 模块。

本实例提供项目完整代码