编写库

除了应用程序,webpack 还可以用于打包 JavaScript 库。本指南旨在帮助库作者简化他们的打包策略。

编写库

我们假设正在编写一个小型库 `webpack-numbers`,它允许用户将数字 1 到 5 从数字形式转换为文本形式,反之亦然,例如 2 转换为 'two'。

基本的项目结构如下所示

项目

+  |- webpack.config.js
+  |- package.json
+  |- /src
+    |- index.js
+    |- ref.json

使用 npm 初始化项目,然后安装 `webpack`、`webpack-cli` 和 `lodash`

npm init -y
npm install --save-dev webpack webpack-cli lodash

我们将 `lodash` 安装为 `devDependencies` 而非 `dependencies`,因为我们不想将其打包到库中,否则我们的库可能会变得臃肿。

src/ref.json

[
  {
    "num": 1,
    "word": "One"
  },
  {
    "num": 2,
    "word": "Two"
  },
  {
    "num": 3,
    "word": "Three"
  },
  {
    "num": 4,
    "word": "Four"
  },
  {
    "num": 5,
    "word": "Five"
  },
  {
    "num": 0,
    "word": "Zero"
  }
]

src/index.js

import _ from 'lodash';
import numRef from './ref.json';

export function numToWord(num) {
  return _.reduce(
    numRef,
    (accum, ref) => {
      return ref.num === num ? ref.word : accum;
    },
    ''
  );
}

export function wordToNum(word) {
  return _.reduce(
    numRef,
    (accum, ref) => {
      return ref.word === word && word.toLowerCase() ? ref.num : accum;
    },
    -1
  );
}

Webpack 配置

让我们从这个基本的 webpack 配置开始

webpack.config.js

const path = require('path');

module.exports = {
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'webpack-numbers.js',
  },
};

在上面的例子中,我们告诉 webpack 将 `src/index.js` 打包到 `dist/webpack-numbers.js`。

暴露库

到目前为止,一切都应该和打包应用程序一样,但不同之处在于——我们需要通过 output.library 选项来暴露入口点的导出。

webpack.config.js

  const path = require('path');

  module.exports = {
    entry: './src/index.js',
    output: {
      path: path.resolve(__dirname, 'dist'),
      filename: 'webpack-numbers.js',
+     library: "webpackNumbers",
    },
  };

我们将入口点暴露为 `webpackNumbers`,这样用户就可以通过 script 标签使用它

<script src="https://example.org/webpack-numbers.js"></script>
<script>
  window.webpackNumbers.wordToNum('Five');
</script>

然而,这仅在通过 script 标签引用时才有效,它不能在 CommonJS、AMD、Node.js 等其他环境中使用。

作为库作者,我们希望它能在不同环境中兼容,即用户应该能够以以下列出的多种方式使用打包后的库

  • CommonJS 模块引用:

    const webpackNumbers = require('webpack-numbers');
    // ...
    webpackNumbers.wordToNum('Two');
  • AMD 模块引用:

    require(['webpackNumbers'], function (webpackNumbers) {
      // ...
      webpackNumbers.wordToNum('Two');
    });
  • script 标签:

    <!DOCTYPE html>
    <html>
      ...
      <script src="https://example.org/webpack-numbers.js"></script>
      <script>
        // ...
        // Global variable
        webpackNumbers.wordToNum('Five');
        // Property in the window object
        window.webpackNumbers.wordToNum('Five');
        // ...
      </script>
    </html>

让我们将 `output.library` 选项的 `type` 设置为 'umd' 来更新它

 const path = require('path');

 module.exports = {
   entry: './src/index.js',
   output: {
     path: path.resolve(__dirname, 'dist'),
     filename: 'webpack-numbers.js',
-    library: 'webpackNumbers',
+    globalObject: 'this',
+    library: {
+      name: 'webpackNumbers',
+      type: 'umd',
+    },
   },
 };

现在 webpack 将会打包一个可以与 CommonJS、AMD 和 script 标签一起使用的库。

外部化 Lodash

现在,如果你运行 `npx webpack`,你会发现生成了一个相当大的包。如果你检查文件,会看到 lodash 已经和你的代码一起打包了。在这种情况下,我们更倾向于将 `lodash` 视为一个对等依赖。这意味着消费者应该已经安装了 `lodash`。因此,你可能会希望将这个外部库的控制权交给你的库的消费者。

这可以通过 externals 配置来实现

webpack.config.js

  const path = require('path');

  module.exports = {
    entry: './src/index.js',
    output: {
      path: path.resolve(__dirname, 'dist'),
      filename: 'webpack-numbers.js',
      library: {
        name: "webpackNumbers",
        type: "umd"
      },
    },
+   externals: {
+     lodash: {
+       commonjs: 'lodash',
+       commonjs2: 'lodash',
+       amd: 'lodash',
+       root: '_',
+     },
+   },
  };

这意味着你的库期望在消费者的环境中有一个名为 `lodash` 的依赖项可用。

外部限制

对于使用依赖项中多个文件的库

import A from 'library/one';
import B from 'library/two';

// ...

你无法通过在 externals 中指定 `library` 来将它们从包中排除。你需要逐个排除它们,或者使用正则表达式。

module.exports = {
  //...
  externals: [
    'library/one',
    'library/two',
    // Everything that starts with "library/"
    /^library\/.+$/,
  ],
};

最后步骤

按照生产环境指南中提到的步骤优化你的生产输出。我们还将生成包的路径添加到 `package.json` 中的 `main` 字段

package.json

{
  ...
  "main": "dist/webpack-numbers.js",
  ...
}

或者,根据本指南将其添加为标准模块

{
  ...
  "module": "src/index.js",
  ...
}

键 `main` 指的是 package.json 中的标准,而 `module` 指的是一个提议,旨在允许 JavaScript 生态系统升级使用 ES2015 模块,同时不破坏向后兼容性。

现在你可以将其发布为 npm 包,并在 unpkg.com 上找到它,以分发给你的用户。

10 贡献者

pksjcejohnstewsimon045angelmarioaccbyzykEugeneHlushkoAnayaDesignchenxsanwizardofhogwarts