Question

Bundler

除了使用 CLI 以外还能使用 API 来初始化打包工具以达成某些进阶功能，如在每次编译时执行一些自订的流程。

下面将用一个监看 (watch) 的範例来解释所有设定选项：

const Bundler = require('parcel-bundler');
const Path = require('path');

// 进入点路径
const entryFiles = Path.join(__dirname, './index.html');
// 或者使用 glob 来指定多个档案
// const entryFiles = './src/*.js';
// 也可使用阵列指定多个档案
// const entryFiles = ['./src/index.html', './some/other/directory/scripts.js'];

// 打包工具选项
const options = {
  outDir: './dist', // 编译后的档案输出路径，预设为 dist
  outFile: 'index.html', // 输出档案名称
  publicUrl: './', // 静态档案的路径，预设为 '/'
  watch: true, // 是否在档案更动时自动重新编译，预设于 process.env.NODE_ENV !== 'production' 时启用
  cache: true, // 是否启用快取，预设为 true
  cacheDir: '.cache', // 快取档案目录，预设为 .cache
  contentHash: false, // 避免档名含有的内文杂凑值
  global: 'moduleName', // 使用此名称汇出一个 UMD 模组，预设为停用
  minify: false, // 档案压缩，若 process.env.NODE_ENV 为 'production'，则会自动启用
  scopeHoist: false, // 启用实验性质的 scope hoisting/tree shaking 功能，可减少 bundle 的大小
  target: 'browser', // browser/node/electron，预设为 browser
  bundleNodeModules: false, // 当 target 设定的环境为 node 及 electron 时，package.json 中的相依套件并不会被加入 bundle 中，若需包含相依套件请将本项设定为 true
  https: { // 定义一对金钥及凭证。设定为 true 将自动产生，设定为 false 则改用 HTTP
    cert: './ssl/c.crt', // 自订凭证路径
    key: './ssl/k.key' // 自订金钥路径
  },
  logLevel: 3,
  /*
    5 = 将所有讯息输出至档案
    4 = 附加时间戳记的详尽讯息，并纪录所有连至开发伺服器的请求
    3 = 纪录所有讯息
    2 = 仅记录错误及警告
    1 = 仅纪录错误
  */
  hmr: true, // 于监看模式时启用或停用模组热替换(HMR)
  hmrPort: 0, // 模组热替换的 socket 连接埠，预设为一个可用的随机连接埠（0 表示可用的随机连接埠）
  sourceMaps: true, // 是否启用 sourcemaps，预设为启用（在最小化编译中强制产生 sourcemap）
  hmrHostname: '', // 模组热替换的域名，预设为 ''
  detailedReport: false // 是否显示更详尽的报表。报表内容包括 bundle、资源、档案大小及编译时间等，预设为 false。报表仅在 watch 停用的情况下才会显示
};

(async function () {
  // 使用进入点路径及选项初始化 bundler
  const bundler = new Bundler(entryFiles, options);

  // 执行 bundler 后将会回传主 bundle
  // 使用监看模式时请使用下列的事件，此 Promise 仅会触发一次，而非每次重新编译时都会触发。
  const bundle = await bundler.bundle();
})();

你可以透过 bundler.serve() 来启动 Parcel 内建的开发伺服器。bundler.serve() 会呼叫 bundler.bundle() 并启动一个简易的 HTTP/HTTPS 伺服器，serve() 接受下列三个参数，这三个参数都非必要项，第一个为连接埠；第二为启用 HTTPS 与否，可设定为一个如 {cert, key} 的物件，其设定值指向金钥及凭证档，也可设定为 true 以产生一个金钥；第三个参数则为主机位址。

事件

下列是所有事件的列表

• Parcel 会在编译完成时触发 bundled 事件，并传入 bundle 实体至回呼函式。

const bundler = new Bundler(...);
bundler.on('bundled', (bundle) => {
  // bundler 包含所有资源及 bundle，详见开发文件
});
// 开始编译
bundler.bundle();

• 每次编译完成后（包括重新编译）buildEnd 事件会被触发，此事件即便编译发生错误仍会被触发。

const bundler = new Bundler(...);
bundler.on('buildEnd', () => {
  // 做点什幺...
});
// 开始编译
bundler.bundle();

• buildStart 事件会于首次编译开始时被触发，并传入一个 entryFiles 阵列至回呼函式。

const bundler = new Bundler(...);
bundler.on('buildStart', entryPoints => {
  // 做点什幺...
});
// 开始编译
bundler.bundle();

• 当编译出错时会触发 buildError 事件，并会将 Error 物件传入回呼函式

const bundler = new Bundler(...);
bundler.on('buildError', error => {
  // 做点什幺...
});
// 开始编译
bundler.bundle();

Bundle

Parcel 使用 Bundle 将所有资源打包在一起，其也包含了子系及旁系 bundle 以便编译出 bundle 树。

属性

• type：其包含的资源类型，如 js、css 或 map …等等
• name：bundle 名称。由 entryAsset 的 Asset.generateBundleName() 产生
• parentBundle：父 bundle。若是入口 bundle 的话则为 null
• entryAsset：bundle 的进入点，用来产生名称及搜集资源
• assets：bundle 中所有资源的集合 (Set)
• childBundles：所有子 bundle 的集合 (Set)
• siblingBundles：所有旁系 bundle 的集合 (Set)
• siblingBundlesMap：所有旁系 bundle 的对应关係 (Map<String(Type: js, css, map, ...), Bundle>)
• offsets：bundle 中所有资源位置的对应关係 (Map<Asset, number(line number inside the bundle)>)，用来产生準确的 source map。

树 (Tree)

Bundle 包含了 parentBundle、childBundles 及 siblingBundles 等属性，并一起建立一个快速迭代的 bundle 树。

下列的基本範例展示了一个资源树及其产生的 bundle 树：

资源树 (Asset tree)：

index.html 引入 index.js 及 index.css.

index.js 引入 test.js 及 test.txt

index.html
-- index.js
 |--- test.js
 |--- test.txt
-- index.css

Bundle 树 (Bundle Tree)：

index.html 被作为主 bundle 的进入资源，主 bundle 建立了两个子 bundle，一个用于 index.js，另一个则用于 index.css，因其类型与 html 不同。

index.js 引入两个档案，test.js 及 test.txt。

test.js 被加入 index.js bundle 的资源中，因其与 index.js 类型相同。

test.txt 建立一个新 bundle 并被加入到 index.js bundle 之中，因其资源类型与 index.js 不同。

index.css 没有引入资源，因此只包含其自身的入口资源。

index.css 及 index.js bundles 为旁系 bundle (siblingBundles)，因为它们共用一个父 bundle。

index.html
-- index.js (包括 index.js 及 test.js)
 |--- test.txt (包括 test.txt)
-- index.css (包括 index.css)

中介软体 (Middleware)

中介软体可用来介入 HTTP 伺服器，如 express 和 node 的 http。

下列範例展示了如何在 express 中使用 Parcel 中介软体

const Bundler = require('parcel-bundler');
const app = require('express')();

const file = 'index.html'; // 传入进入点的绝对路径
const options = {}; // 详细介绍请见 API 文件中的选项说明区块

// 使用档案及选项来初始化 bundler
const bundler = new Bundler(file, options);

// 让 express 使用 bundler 的中介软体，如此一来 Parcel 将会处理 express 伺服器上的所有请求
app.use(bundler.middleware());

// 监听连接埠 8080
app.listen(8080);