Parcel API

API

Bundler

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

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

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

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

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

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

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

事件

這是所有的 bundler 事件列表。

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

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

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

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

• 首次構(gòu)建會(huì)調(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)的錯(cuò)誤都會(huì)調(diào)用 buildError，Error對(duì)象作為參數(shù)傳遞給回調(diào)函數(shù)。

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

Bundle

Bundle 是 parcel 用來(lái)將資源打包在一起的工具，它還包含能夠構(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)> ，用于生成準(zhǔn)確的 sourcemap 。

樹

Bundle 包含一個(gè) parentBundle，childBundles 和 siblingBundles，所有這些屬性一起創(chuàng)建一個(gè)快速迭代的 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 的入口資源，這個(gè)主 bundle 創(chuàng)建了兩個(gè)子 bundle ，一個(gè)用于 index.js，另一個(gè)用于 index.css ，這是因?yàn)樗鼈兣c html 的類型不同。

index.js 引入了兩個(gè)文件，test.js 和 test.txt。

test.js 被添加到了 index.js bundle 的資源中，因?yàn)樗c index.js 的類型相同。

test.txt 會(huì)創(chuàng)建一個(gè)新的 bundle，并被添加到 index.js bundle 的子元素中，因?yàn)樗桥c index.js 不同的資源類型。

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

index.css 和 index.js 這兩個(gè) 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'; // 傳入一個(gè)絕對(duì)路徑，作為入口文件
const options = {}; // 有關(guān) options 的具體配置，請(qǐng)參考 api 文檔

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

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

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