Parcel API

Parcel API 可用於以程式化方式執行建置或監控專案變更。它與 Parcel CLI 使用的 API 相同。當您需要更多彈性，或需要將 Parcel 整合到其他建置系統時，請使用 API。

Parcel 建構函式

#

Parcel API 可透過 @parcel/core 套件使用。您還需要一個預設設定檔，例如 @parcel/config-default。

yarn add @parcel/core @parcel/config-default

接著，將此套件匯入您的程式並呼叫 Parcel 建構函式。它接受 InitialParcelOptions 物件，其中包含 Parcel CLI 使用的所有選項，以及更多選項。

有兩個必填參數

build.mjs 
import {Parcel} from '@parcel/core';

let bundler = new Parcel({
  entries: 'a.js',
  defaultConfig: '@parcel/config-default'
});

目標

#

預設情況下，Parcel 會執行開發建置，但這可以透過將 mode 選項設定為 production 來變更，這會啟用範圍提升、縮小化等。請參閱 生產。

您也可以使用 defaultTargetOptions 來設定 目標 的值，如果它們未在專案中設定。例如，若要覆寫預設的瀏覽器目標，請使用 engines 選項。

build.mjs 
import {Parcel} from '@parcel/core';

let bundler = new Parcel({
  entries: 'a.js',
  defaultConfig: '@parcel/config-default',
  mode: 'production',
  defaultTargetOptions: {
    engines: {
      browsers: ['last 1 Chrome version']
    }
  }
});

當設定為陣列時，targets 選項可用於指定專案的哪些目標（如 package.json 中所述）要建置。例如，若要只建置專案的 modern 目標

build.mjs 
import {Parcel} from '@parcel/core';

let bundler = new Parcel({
  entries: 'a.js',
  defaultConfig: '@parcel/config-default',
  targets: ['modern']
});

或者，targets 可以設定為物件，它將會覆寫專案中定義的任何目標。請參閱 目標 以取得有關可用選項的更多詳細資訊。

build.mjs 
import {Parcel} from '@parcel/core';

let bundler = new Parcel({
  entries: 'a.js',
  defaultConfig: '@parcel/config-default',
  mode: 'production',
  targets: {
    modern: {
      engines: {
        browsers: ['last 1 Chrome version']
      }
    },
    legacy: {
      engines: {
        browsers: ['IE 11']
      }
    }
  }
});

環境變數

#

環境變數，例如 NODE_ENV，可以使用 env 選項設定。這允許設定變數，而不會覆寫 process.env 上的值。

build.mjs 
import {Parcel} from '@parcel/core';

let bundler = new Parcel({
  entries: 'a.js',
  defaultConfig: '@parcel/config-default',
  mode: 'production',
  env: {
    NODE_ENV: 'production'
  }
});

報告器

#

預設情況下，當您使用 API 時，Parcel 不會將任何輸出寫入 CLI。這表示它不會報告狀態資訊，也不會為診斷提供漂亮的格式。可以使用 additionalReporters 選項來啟用這些功能，它會在 .parcelrc 中指定的任何報告器之外執行。@parcel/reporter-cli 外掛程式提供 CLI 使用的預設報告器，但您也可以使用任何其他報告器外掛程式。

build.mjs 
import {Parcel} from '@parcel/core';
import {fileURLToPath} from 'url';

let bundler = new Parcel({
  entries: 'a.js',
  defaultConfig: '@parcel/config-default',
  additionalReporters: [
    {
      packageName: '@parcel/reporter-cli',
      resolveFrom: fileURLToPath(import.meta.url)
    }
  ]
});

建置

#

建立 Parcel 執行個體後，您可以使用它來建置專案或監控變更。若要建置一次，請使用 run API。這會傳回一個 Promise，如果建置成功，它將使用包含 BundleGraph 和一些其他資訊的 BuildSuccessEvent 來解析，或者如果建置失敗，則會拒絕錯誤。建置錯誤會有一個或多個 Diagnostic 物件附加在它們上，其中包含錯誤的詳細資訊。

build.mjs 
import {Parcel} from '@parcel/core';

let bundler = new Parcel({
  entries: 'a.js',
  defaultConfig: '@parcel/config-default'
});

try {
  let {bundleGraph, buildTime} = await bundler.run();
  let bundles = bundleGraph.getBundles();
  console.log(`✨ Built ${bundles.length} bundles in ${buildTime}ms!`);
} catch (err) {
  console.log(err.diagnostics);
}

觀看

#

若要觀看專案變更並收到每個重新建置的通知，請使用 watch API。傳遞一個回呼，以便在建置成功或失敗時呼叫。回呼會收到一個錯誤參數和一個事件物件。錯誤參數僅用於觀看期間的致命錯誤。正常的建置失敗會由 BuildFailureEvent 表示，其中包含 Diagnostic 物件的清單。

watch 也會傳回一個訂閱物件，當您要停止觀看時，您應該呼叫 unsubscribe 方法。

build.mjs 
import {Parcel} from '@parcel/core';

let bundler = new Parcel({
  entries: 'a.js',
  defaultConfig: '@parcel/config-default'
});

let subscription = await bundler.watch((err, event) => {
  if (err) {
    // fatal error
    throw err;
  }

  if (event.type === 'buildSuccess') {
    let bundles = event.bundleGraph.getBundles();
    console.log(`✨ Built ${bundles.length} bundles in ${event.buildTime}ms!`);
  } else if (event.type === 'buildFailure') {
    console.log(event.diagnostics);
  }
});

// some time later...
await subscription.unsubscribe();

開發伺服器

#

開發伺服器包含在預設的 Parcel 組態中。它可以透過傳遞 serveOptions 給 Parcel 建構函式並在觀看模式中執行 Parcel 來啟用。熱重載可以透過設定 hmrOptions 來啟用。port 是唯一需要的選項，但其他選項（例如 HTTPS 選項）也可以設定。

build.mjs 
import {Parcel} from '@parcel/core';

let bundler = new Parcel({
  entries: 'a.js',
  defaultConfig: '@parcel/config-default',
  serveOptions: {
    port: 3000
  },
  hmrOptions: {
    port: 3000
  }
});

await bundler.watch();

檔案系統

#

Parcel 在核心和大多數外掛程式中使用抽象的檔案系統。預設情況下，它依賴於 Node.js fs API，但 Parcel 也有 MemoryFS 實作。您可以使用 inputFS 選項來覆寫 Parcel 從中讀取來源檔案的檔案系統，並使用 outputFS 選項來覆寫 Parcel 將輸出（包括快取）寫入的檔案系統。

MemoryFS 位於 @parcel/fs 套件中。建構它需要傳遞一個 WorkerFarm 執行個體，以便檔案系統可以從多個執行緒讀取和寫入。您需要使用從 @parcel/core 匯出的 createWorkerFarm 函數建立一個工作農場，並將其傳遞給 MemoryFS 和 Parcel 建構函數。完成後，請務必對工作農場呼叫 end 以允許程序退出。

此範例將其輸出寫入記憶體檔案系統，並記錄每個建置套件的內容。

build.mjs 
import {Parcel, createWorkerFarm} from '@parcel/core';
import {MemoryFS} from '@parcel/fs';

let workerFarm = createWorkerFarm();
let outputFS = new MemoryFS(workerFarm);

let bundler = new Parcel({
  entries: 'a.js',
  defaultConfig: '@parcel/config-default',
  workerFarm,
  outputFS
});

try {
  let {bundleGraph} = await bundler.run();

  for (let bundle of bundleGraph.getBundles()) {
    console.log(bundle.filePath);
    console.log(await outputFS.readFile(bundle.filePath, 'utf8'));
  }
} finally {
  await workerFarm.end();
}