API

Bundler

你可以選擇使用 API 替代 CLI 來初始化 bundler 對象，以獲取更高級的使用方式(例如：在每次構(gòu)建時進行自定義操作)。 針對每個選項都給出了可參考的示例進行解釋說明：

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

// 單個入口文件路徑
const entryFiles = Path.join(__dirname, './index.html');
// 或多個入口文件路徑
// 1.glob模式
const entryFiles = './src/*.js';
// 2.數(shù)組格式
const entryFiles = ['./src/index.html', './some/other/directory/scripts.js'];

// Bundler 選項
const options = {
  outDir: './dist', // 將生成的文件放入輸出目錄下，默認為 dist
  outFile: 'index.html', // 輸出文件的名稱
  publicUrl: './', // 靜態(tài)資源的 url ，默認為 '/'
  watch: true, // 是否需要監(jiān)聽文件并在發(fā)生改變時重新編譯它們，默認為 process.env.NODE_ENV !== 'production'
  cache: true, // 啟用或禁用緩存，默認為 true
  cacheDir: '.cache', // 存放緩存的目錄，默認為 .cache
  contentHash: false, // 禁止文件名hash
  global: 'moduleName', // 在當前名字模塊以UMD模式導(dǎo)出，默認禁止。
  minify: false, // 壓縮文件，當 process.env.NODE_ENV === 'production' 時，會啟用
  scopeHoist: false, // 打開實驗性的scope hoisting/tree shaking用來縮小生產(chǎn)環(huán)境的包。
  target: 'browser', // browser/node/electron, 默認為 browser
  bundleNodeModules: false, // 當package.json的'target'設(shè)置'node' or 'electron'時，相應(yīng)的依賴不會加入bundle中。設(shè)置true將被包含。
  https: { // 設(shè)置true自動定義一對密鑰和證書，false取消變成http
    cert: './ssl/c.crt', // 自定義證書路徑
    key: './ssl/k.key' // 自定義密鑰路徑
  },
  logLevel: 3,
  /**
   * 5 = 儲存每個信息
   * 4 = 輸出信息、警告和錯誤附加時間戳和dev服務(wù)的http請求
   * 3 = 輸出信息、警告和錯誤
   * 2 = 輸出警告和錯誤
   * 1 = 輸出錯誤
  */
  hmr: true, // 開啟或禁止HRM
  hmrPort: 0, // hmr socket 運行的端口，默認為隨機空閑端口(在 Node.js 中，0 會被解析為隨機空閑端口)
  sourceMaps: true, // 啟用或禁用 sourcemaps，默認為啟用(在精簡版本中不支持)
  hmrHostname: '', // 熱模塊重載的主機名，默認為 ''
  detailedReport: false // 打印 bundles、資源、文件大小和使用時間的詳細報告，默認為 false，只有在禁用監(jiān)聽狀態(tài)時才打印報告
};

(async function() {
  // 使用提供的入口文件路徑和選項初始化 bundler
  const bundler = new Bundler(entryFiles, options);

  // 運行 bundler，這將返回主 bundle
  // 如果你正在使用監(jiān)聽模式，請使用下面這些事件，這是因為該 promise 只會觸發(fā)一次，而不是每次重新構(gòu)建時都觸發(fā)
  const bundle = await bundler.bundle();
})();

你可以使用 bundler.serve() 啟動內(nèi)建于 Parcel 的開發(fā)服務(wù)器。bundler.serve()會調(diào)用bundler.bundle()啟動一個簡易的 HTTP/HTTPS 服務(wù)器。serve()接受三個非必填參數(shù)，第一個是端口，第二個是啟動 https（可以設(shè)置為一個{cert, key}對象指向 key 和 cert 的路徑或者 true 自動生成證書），第三個是主機地址 host。

事件

這是所有的 bundler 事件列表。

• 一旦 parcel 完成打包，會調(diào)用 bundled，主 bundle 會作為參數(shù)傳遞到該 callback

const bundler = new Bundler(...);
bundler.on('bundled', (bundler) => {
  // bundler 包含所有資源和 bundle，如需了解更多請查看文檔
});
// 開始構(gòu)建調(diào)用
bundler.bundle();

• 每次構(gòu)建結(jié)束后，都會調(diào)用 buildEnd，即使發(fā)生錯誤它也仍然會被觸發(fā)

const bundler = new Bundler(...);
bundler.on('buildEnd', () => {
  // 做一些操作……
});
// 開始構(gòu)建調(diào)用
bundler.bundle();

• 首次構(gòu)建會調(diào)用 buildStart，entryFiles數(shù)組作為參數(shù)傳遞給回調(diào)函數(shù)

const bundler = new Bundler(...);
bundler.on('buildStart', entryPoints => {
  // 做一些操作……
});
// 開始構(gòu)建調(diào)用
bundler.bundle();

• 構(gòu)建中出現(xiàn)的錯誤都會調(diào)用 buildError，Error對象作為參數(shù)傳遞給回調(diào)函數(shù)。

const bundler = new Bundler(...);
bundler.on('buildError', error => {
  // 做一些操作……
});
// 開始構(gòu)建調(diào)用
bundler.bundle();

Bundle

Bundle 是 parcel 用來將資源打包在一起的工具，它還包含能夠構(gòu)建出 bundle 樹的子 bundle 和兄弟 bundle。

屬性

• type：它包含的資源類型 (例如：js, css, map, ...)
• name：bundle 的名稱 (使用 entryAsset 的 Asset.generateBundleName() 生成)
• parentBundle：父 bundle ，入口 bundle 的父 bundle 是 null
• entryAsset：bundle 的入口，用于生成名稱(name)和聚攏資源(assets)
• 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)> ，用于生成準確的 sourcemap 。

樹

Bundle 包含一個 parentBundle，childBundles 和 siblingBundles，所有這些屬性一起創(chuàng)建一個快速迭代的 bundle 樹。

資源樹及其生成的 bundle 樹的基本示例如下:

資源樹：

index.html 引用 index.js 和 index.css

index.js 引用 test.js 和 test.txt

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

Bundle 樹:

index.html 被作為主 bundle 的入口資源，這個主 bundle 創(chuàng)建了兩個子 bundle ，一個用于 index.js，另一個用于 index.css ，這是因為它們與 html 的類型不同。

index.js 引入了兩個文件，test.js 和 test.txt。

test.js 被添加到了 index.js bundle 的資源中，因為它與 index.js 的類型相同。

test.txt 會創(chuàng)建一個新的 bundle，并被添加到 index.js bundle 的子元素中，因為它是與 index.js 不同的資源類型。

index.css 沒有引用資源，因此只包含它的入口資源。

index.css 和 index.js 這兩個 bundle 為共享同一父 bundle 的兄弟 bundle(siblingBundles)。

index.html
-- index.js (includes index.js and test.js)
 |--- test.txt (includes test.txt)
-- index.css (includes index.css)

中間件(Middleware)

中間件可以用于 hook 到 http 服務(wù)器(例如：express 或者 Node.js http) 。

使用 express 的 parcel 中間件示例：

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

const file = 'index.html'; // 傳入一個絕對路徑，作為入口文件
const options = {}; // 有關(guān) options 的具體配置，請參考 api 文檔

// 使用 file 和 options 參數(shù)，初始化新的 bundler
const bundler = new Bundler(file, options);

// 讓 express 使用 bundler 中間件，這將讓 parcel 處理你 express 服務(wù)器上的每個請求
app.use(bundler.middleware());

// 監(jiān)聽 8080 端口
app.listen(8080);