外掛

Parcel 適用於許多專案，無需任何組態即可立即使用。但如果您想要更多控制權，或需要延伸或覆寫 Parcel 的預設值，您可以透過在專案中建立一個 .parcelrc 檔案來達成。

Parcel 的設計非常模組化。Parcel 核心本身幾乎沒有針對建置 JavaScript 或網頁進行特定設定，所有行為都是透過外掛來指定。針對建置的每個階段都有特定的外掛類型，因此您可以自訂幾乎所有內容。

.parcelrc

Parcel 組態會指定在 .parcelrc 檔案中。它是使用 JSON5 編寫的，類似於 JSON，但支援註解、未加引號的鍵、尾隨逗號和其他功能。

延伸組態

Parcel 的預設組態會指定在 @parcel/config-default 中。大多數時候，您會想要在自己的 Parcel 組態中延伸它。要這麼做，請在 .parcelrc 中使用 extends 欄位。

{
  "extends": "@parcel/config-default"
}

您也可以透過傳遞陣列來延伸多個組態。組態會按照指定的順序合併。

{
  "extends": ["@parcel/config-default", "@company/parcel-config"]
}

您也可以使用相對路徑來參照專案中的其他組態。

{
  "extends": "../.parcelrc"
}

延伸的組態也可以延伸其他組態，形成組態鏈。

Glob 地圖

.parcelrc 中的許多欄位，例如 transformers 或 packagers，使用物件作為 glob 的地圖，並對應到外掛程式名稱。這讓您可以透過檔案副檔名、檔案路徑，甚至特定檔案名稱來設定 Parcel 的行為。Glob 會相對於包含 .parcelrc 的目錄進行比對。

Glob 地圖中欄位的順序會定義它們在測試檔案名稱時所具有的優先順序。這讓您可以為專案中的特定檔案設定不同的行為，例如特定目錄中的檔案。

{
  "transformers": {
    "icons/*.svg": ["highest-priority"],
    "*.svg": ["lowest-priority"]
  }
}

如果我們嘗試為檔案 icons/home.svg 尋找轉換，我們會逐一比對 glob，直到找到符合的項目，也就是 icons/*.svg。我們永遠不會到達 *.svg。

檢查完目前設定中的所有 glob 之後，Parcel 會回溯到任何延伸設定中所定義的 glob。

管線

.parcelrc 中的許多欄位，例如 transformers、optimizers 和 reporters，接受一系列會串行執行的外掛程式陣列。這些稱為管線。

如果您想定義優先順序較高的管線，用來延伸優先順序較低的管線，而不是覆寫它，您可以使用特殊的 "..." 語法。在管線中加入這個語法，即可將下一個優先順序的管線嵌入其中。您可以將它插入管線的開頭、結尾，甚至中間，這讓您可以完全控制管線的延伸方式。

{
  "transformers": {
    "icons/*.svg": ["@company/parcel-transformer-svg-icons", "..."],
    "*.svg": ["@parcel/transformer-svg"]
  }
}

在上方的範例中，在處理 icons/home.svg 時，我們會先執行 @company/parcel-transformer-svg-icons，然後執行 @parcel/transformer-svg。

這也適用於已延伸的設定。如果使用了 "..."，而且在目前的設定中沒有定義優先順序較低的管線，Parcel 會回溯到延伸設定中所定義的管線。

由於 @parcel/transformer-svg 包含在預設設定中，因此上述範例可以改寫成這樣

{
  "extends": "@parcel/config-default",
  "transformers": {
    "icons/*.svg": ["@company/parcel-transformer-svg-icons", "..."]
  }
}

命名管線

除了基於 glob 的管道，Parcel 還支援命名管道，讓你可以用多種方式匯入同一個檔案。命名管道在 .parcelrc 中定義，就像一般的管道一樣，不過在 glob 的開頭加入 URL 範例。

例如，預設情況下，匯入圖片通常會傳回外部檔案的 URL，但你可以使用預設 Parcel 設定中定義的 data-url: 命名管道，將其內嵌為資料 URL。詳細資訊請參閱 套件內嵌。

.logo {
  background: url(data-url:./logo.png);
}

你也可以定義自己的命名管道。例如，你可以定義一個 arraybuffer: 命名管道，讓你可以將檔案匯入為 ArrayBuffer。在此範例中，* glob 會符合任何檔案，但你也可以使用更明確的 glob。"..." 語法用於讓 Parcel 在執行 parcel-transformer-arraybuffer 外掛程式將其轉換為 ArrayBuffer 之前，以正常方式處理檔案。

{
  "extends": "@parcel/config-default",
  "transformers": {
    "arraybuffer:*": ["...", "parcel-transformer-arraybuffer"]
  }
}

import buffer from 'arraybuffer:./file.png';

命名管道支援轉換器和最佳化器管道。對於轉換器，管道會在參考資源的依賴項中指定。對於最佳化器，管道會從套件的進入資源繼承。

外掛

Parcel 支援許多不同類型的外掛程式，它們會在建置過程中執行特定任務。外掛程式會在 .parcelrc 中使用其 NPM 套件名稱來參考。

轉換器

尋找轉換器外掛程式

轉換器 外掛程式會轉換單一資源以編譯它、找出依賴項，或將其轉換為不同的格式。它們會使用 .parcelrc 中的 glob 對應 來設定。多個轉換器可以使用 管道 在同一個資源上串列執行，且支援 命名管道，以允許在同一個專案中以多種不同方式編譯同一個檔案。"..." 語法可以用來延伸檔案的預設轉換器。

{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.svg": ["...", "@parcel/transformer-svg-react"]
  }
}

編譯資產時，其檔案類型可能會改變。例如，編譯 TypeScript 時，資產的類型會從 ts 或 tsx 變更為 js。發生這種情況時，Parcel 會重新評估如何進一步處理資產，並針對 .js 檔案執行相符的處理程序。

{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.{ts,tsx}": ["@parcel/transformer-typescript-tsc"]
  }
}

解析器

尋找解析器外掛程式

解析器 外掛程式負責將依賴項規格轉換為完整的檔案路徑，而轉換器會處理該路徑。有關其運作方式的詳細資訊，請參閱 依賴項解析。解析器會使用 .parcelrc 中的外掛程式名稱陣列進行設定。解析會依序處理外掛程式清單，直到其中一個外掛程式傳回結果。

"..." 語法可用於延伸預設的解析器。這允許您覆寫特定依賴項的解析，但對其他依賴項則採用預設值。通常，您會希望在執行預設解析器之前加入自訂解析器。

{
  "extends": "@parcel/config-default",
  "resolvers": ["@company/parcel-resolver", "..."]
}

如果省略 "..."，您的解析器必須能夠處理所有依賴項，否則解析會失敗。

打包器（實驗性質）

尋找打包器外掛程式

打包器 外掛程式負責將資產分組成套件。打包器可以透過在 .parcelrc 中指定外掛程式名稱來設定。

{
  "extends": "@parcel/config-default",
  "bundler": "@company/parcel-bundler"
}

執行時期（實驗性質）

尋找執行時期外掛

執行時期外掛允許您將資產注入到套件中。它們可以使用 .parcelrc 中的外掛名稱陣列進行設定。此清單中的所有執行時期外掛都會在每個套件中執行。"..." 語法可用於延伸預設執行時期。

{
  "extends": "@parcel/config-default",
  "runtimes": ["@company/parcel-runtime", "..."]
}

如果省略 "..."，預設執行時期將不會執行。這可能會造成問題，因為許多 Parcel 功能都仰賴預設執行時期。

命名器

尋找命名器外掛

命名器外掛決定套件的輸出檔名。它們可以使用 .parcelrc 中的外掛名稱陣列進行設定。命名會依序處理命名器清單，直到其中一個傳回結果為止。

"..." 語法可用於延伸預設命名器。這允許您覆寫特定套件的命名，但對其他套件則採用預設設定。一般來說，您會希望在執行預設命名器之前加入自訂命名器。

{
  "extends": "@parcel/config-default",
  "namers": ["@company/parcel-namer", "..."]
}

如果省略 "..."，您的命名器必須能夠處理所有套件的命名，否則建置將會失敗。

封裝器

尋找封裝器外掛

封裝器外掛負責將套件中的所有資產組合成一個輸出檔案。它們使用 .parcelrc 中的glob 對應進行設定。Glob 會與套件的輸出檔名進行比對。可以設定單一封裝器外掛在每個套件中執行。

{
  "extends": "@parcel/config-default",
  "packagers": {
    "*.{jpg,png}": "@company/parcel-packager-image-sprite"
  }
}

最佳化器

尋找最佳化器外掛

Optimizer 外掛類似於轉換器，但它們接受的是捆綁包，而不是單一資產。它們使用 .parcelrc 中的 glob 映射 進行設定。多個最佳化器可以使用 管線 在同一個捆綁包上依序執行，而 命名管線 則支援在同一個專案中以多種不同方式編譯同一個捆綁包。"..." 語法可用於擴充捆綁包的預設最佳化器。

{
  "extends": "@parcel/config-default",
  "optimizers": {
    "*.js": ["@parcel/optimizer-esbuild"]
  }
}

壓縮器

尋找壓縮器外掛

壓縮器 外掛會在將最終捆綁包寫入磁碟時使用，並可能以某種方式壓縮或編碼它（例如 Gzip）。它們使用 .parcelrc 中的 glob 映射 進行設定。多個壓縮器可以使用 管線 在同一個捆綁包上執行。每個壓縮器外掛會產生一個額外的檔案以並行寫入，例如 bundle.js、bundle.js.gz 和 bundle.js.br。"..." 語法可用於擴充捆綁包的預設壓縮器。

{
  "extends": "@parcel/config-default",
  "compressors": {
    "*.{js,html,css}": [
      "...",
      "@parcel/compressor-gzip",
      "@parcel/compressor-brotli"
    ]
  }
}

報告器

尋找報告器外掛

報告器 外掛會在建置過程中接收 Parcel 的事件。例如，報告器可能會將狀態資訊寫入 stdout、執行開發伺服器，或在建置結束時產生捆綁包分析報告。報告器使用 .parcelrc 中的套件名稱陣列進行設定。此清單中的所有報告器都會在每個建置事件中執行。"..." 語法可用於擴充預設報告器。

{
  "extends": "@parcel/config-default",
  "reporters": ["...", "@parcel/reporter-bundle-analyzer"]
}

您不常使用的報告器也可以使用 --reporter 選項在 CLI 中指定，或透過 API 使用 additionalReporters 選項指定。在 .parcelrc 中指定的報告器會一直執行。

本機外掛

大部分的 Parcel 外掛都是 NPM 套件。這表示它們有宣告與 Parcel 相容的版本，以及任何它們可能有的依賴項的 package.json。它們也必須遵循命名系統以確保清楚易懂。

通常，Parcel 外掛會發布到 NPM 註冊表，或內部公司註冊表（例如 Artifactory）。這鼓勵外掛與社群或公司內專案分享，以避免重複。

不過，在開發外掛時，在不先發布的情況下直接在專案中執行它會很有用。有幾種方法可以做到這一點。

相對檔案路徑

外掛可以從使用它們的 .parcelrc 設定檔中作為相對路徑來參照。這些可能是 CommonJS 或 ESM 模組，使用 .mjs 或 .cjs 副檔名，或最近的 package.json 中的 "type": "module" 欄位來決定（與 Node 載入模組的方式相同）。

{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.js": ["./my-local-plugin.mjs", "..."]
  }
}

Yarn 和 NPM 工作區

使用本機外掛的另一種方法是透過 Yarn 工作區 或 NPM 工作區 使用 monorepo 設定。這允許你依賴儲存庫中其他套件，就像你依賴已發布的套件一樣。若要執行此操作，請設定如下專案結構

project
├── .parcelrc
├── package.json
└── packages
    ├── app
    │   └── package.json
    └── parcel-transformer-foo
        ├── package.json
        └── src
            └── FooTransformer.js

在根目錄的 package.json 中，使用 workspaces 欄位來參照你的套件。

{
  "name": "my-project",
  "private": true,
  "workspaces": ["packages/*"]
}

然後，在你的 .parcelrc 中，你可以參照 parcel-transformer-foo，就像參照已發布的套件一樣。每當你更新外掛的程式碼時，Parcel 都會重建你的專案。

你也可以選擇將你的應用程式保留在根目錄（例如在 src 資料夾中），而不是放在 packages/app 中。

link: 協定

Yarn 支援使用 link: 協定定義依賴項，以將本機目錄參照為套件。例如，你可以設定如下專案結構

project
├── .parcelrc
├── package.json
├── src
│   └── index.html
└── parcel-transformer-foo
    ├── package.json
    └── src
        └── FooTransformer.js

在根目錄的 package.json 中，你可以使用 link: 協定定義對 parcel-transformer-foo 套件的依賴項。

{
  "name": "my-project",
  "dependencies": {
    "parcel": "^2.0.0",
    "parcel-transformer-foo": "link:./parcel-transformer-foo"
  }
}

然後，在你的 .parcelrc 中，你可以參照 parcel-transformer-foo，就像參照已發布的套件一樣。每當你更新外掛的程式碼時，Parcel 都會重建你的專案。