Bundler

外掛類型：將資產圖形轉換成套件圖形

Bundler API 仍處於實驗階段，因此可能會變更，即使是在小幅更新之間。

Bundler 會接受整個資產圖形，並修改它以新增套件節點，將資產分組成輸出套件。

import { Bundler } from "@parcel/plugin";

export default new Bundler({
  async bundle({ graph }) {
    // ...
  },

  async optimize({ graph }) {
    // ...
  },
});

相關 API

TraversalActions parcel/packages/core/types/index.js:1115

用於控制遍歷

type TraversalActions = {|

  skipChildren(): void,

略過目前節點的子節點，並在佇列中還有其他節點時繼續遍歷。

  stop(): void,

停止遍歷

|}

由下列項目參照

GraphTraversalCallback

GraphVisitor parcel/packages/core/types/index.js:1126

基本上是 GraphTraversalCallback，但允許新增特定的節點進入和離開回呼。

類型

type GraphVisitor<TNode, TContext> = GraphTraversalCallback<TNode, TContext> | {|
  enter?: GraphTraversalCallback<TNode, TContext>,
  exit?: GraphTraversalCallback<TNode, TContext>,
|};

由下列項目參照

Bundle、BundleGraph

GraphTraversalCallback parcel/packages/core/types/index.js:1139

圖形遍歷的一般回呼

參數說明

context：父節點的回傳值會作為參數傳遞給子節點的回呼函式。這可以用於在 DFS 中將資訊從父節點轉發給子節點（與全域變數不同）。

類型

type GraphTraversalCallback<TNode, TContext> = (node: TNode, context: ?TContext, actions: TraversalActions) => ?TContext;

由下列項目參照

GraphVisitor

BundleTraversable parcel/packages/core/types/index.js:1148

類型

type BundleTraversable = {|
  +type: 'asset',
  value: Asset,
|} | {|
  +type: 'dependency',
  value: Dependency,
|};

由下列項目參照

Bundle

BundleGraphTraversable parcel/packages/core/types/index.js:1155

類型

type BundleGraphTraversable = {|
  +type: 'asset',
  value: Asset,
|} | {|
  +type: 'dependency',
  value: Dependency,
|};

由下列項目參照

BundleGraph

CreateBundleOpts parcel/packages/core/types/index.js:1171

MutableBundleGraph 的 createBundle 選項。
如果提供了 entryAsset，則會從 entryAsset 推斷出 uniqueKey（用於 bundle ID）、type 和 env。
如果未提供 entryAsset，則必須提供 uniqueKey（用於 bundle ID）、type 和 env。
isSplittable 預設為 entryAsset.isSplittable 或 false

類型

type CreateBundleOpts =
{|
  +entryAsset: Asset,
  +target: Target,
  +needsStableName?: ?boolean,
  +bundleBehavior?: ?BundleBehavior,
|}
| {|
  +type: string,
  +env: Environment,
  +uniqueKey: string,
  +target: Target,
  +needsStableName?: ?boolean,
  +bundleBehavior?: ?BundleBehavior,
  +isSplittable?: ?boolean,
  +pipeline?: ?string,
|};

由下列項目參照

MutableBundleGraph

Bundle parcel/packages/core/types/index.js:1255

Bundle（一組資源）

interface Bundle {

  +id: string,

Bundle ID。

  +type: string,

Bundle 類型。

  +env: Environment,

Bundle 的環境。

  +target: Target,

Bundle 的目標。

  +needsStableName: ?boolean,

在載入 bundle 時執行的資源（例如，可以新增執行時期）。驗證

  +bundleBehavior: ?BundleBehavior,

控制 bundle 的行為。用於判斷何時載入 bundle。

inline：內嵌 bundle 不會寫入到獨立的檔案中，而是嵌入到父 bundle 中。
isolated：Bundle 會與其父 bundle 隔離。共用資源會被複製。

  +isSplittable: ?boolean,

是否可以拆分套件。如果為 false，則套件的所有相依性會保留在套件內部，而不是參照其他套件。這可能會導致資產在多個套件之間重複，但對於伺服器端渲染等事項可能很有用。

  +hashReference: string,

套件內容雜湊的佔位符，可用於套件名稱或其他套件的內容中。雜湊參照會在封裝和最佳化後，以套件的內容雜湊取代。

  getEntryAssets(): Array<Asset>,

傳回在套件載入時立即執行的資產。有些套件可能沒有任何進入資產，例如共用套件。

  getMainEntry(): ?Asset,

傳回套件的主要進入點，它會提供套件的匯出。有些套件沒有主要進入點，例如共用套件。

  hasAsset(Asset): boolean,

傳回套件是否包含指定的資產。

  hasDependency(Dependency): boolean,

傳回套件是否包含指定的相依性。

  traverseAssets<TContext>(visit: GraphVisitor<Asset, TContext>, startAsset?: Asset): ?TContext,

遍歷套件中的資產。

  traverse<TContext>(visit: GraphVisitor<BundleTraversable, TContext>): ?TContext,

遍歷套件中的資產和相依性。

由下列項目參照

BundleGraph、MutableBundleGraph、NamedBundle、Namer、OptimizingProgressEvent、Packager、PackagingProgressEvent

NamedBundle parcel/packages/core/types/index.js:1318

由 Namer 命名過的 Bundle

interface NamedBundle extends Bundle {

  +publicId: string,

套件 ID 的縮短版本，用於在執行階段參照套件。

  +name: string,

套件名稱。這是相對於套件目標目錄的檔案路徑。套件名稱可能包含雜湊參照，但不包含最終內容雜湊。

  +displayName: string,

套件名稱的版本，已移除雜湊參照以供顯示。

由下列項目參照

BuildSuccessEvent、BundledProgressEvent、Optimizer、OptimizingProgressEvent、PackagedBundle、Packager、PackagingProgressEvent、Runtime

BundleGroup parcel/packages/core/types/index.js:1341

一組同層級的 bundle（儲存在 BundleGraph 中），應該一起（依序）載入。

interface BundleGroup {

  +target: Target,

bundle group 的目標。

  +entryAssetId: string,

bundle group 中的 entry asset 的 id，當 bundle group 載入時會立即執行。

由下列項目參照

BundleGraph、MutableBundleGraph

MutableBundleGraph parcel/packages/core/types/index.js:1353

一個可以在 Bundler 中修改的 BundleGraph

標記為實驗性質

interface MutableBundleGraph extends BundleGraph<Bundle> {

  addAssetGraphToBundle(Asset, Bundle, shouldSkipDependency?: (Dependency) => boolean): void,

將 asset 和所有子節點加入 bundle。

  addAssetToBundle(Asset, Bundle): void,

  addEntryToBundle(Asset, Bundle, shouldSkipDependency?: (Dependency) => boolean): void,

將 asset 作為 entry 加入 bundle。當 bundle 載入時會立即執行 entry asset。

  addBundleToBundleGroup(Bundle, BundleGroup): void,

將 Bundle 加入 BundleGroup，並與 group 中的其他 bundle 一起載入

  createAssetReference(Dependency, Asset, Bundle): void,

  createBundleReference(Bundle, Bundle): void,

  createBundle(CreateBundleOpts): Bundle,

  createBundleGroup(Dependency, Target): BundleGroup,

將邊緣（Dependency -> Asset-s）轉換成（Dependency -> BundleGroup -> Asset-s）

  getDependencyAssets(Dependency): Array<Asset>,

  getParentBundlesOfBundleGroup(BundleGroup): Array<Bundle>,

取得非同步載入此 bundle 的 Bundle。

  getTotalSize(Asset): number,

  removeAssetGraphFromBundle(Asset, Bundle): void,

遞迴地從 bundle 中移除 asset 及其相依性。在 bundle group 邊界停止。

  removeBundleGroup(bundleGroup: BundleGroup): void,

從圖形中移除 BundleGroup。如果 group 中的任何 Bundle 不再存在於圖形中，也會將其移除。

  internalizeAsyncDependency(bundle: Bundle, dependency: Dependency): void,

將對不同 bundle 的相依性轉換成對 bundle 內部 asset 的相依性。

由下列項目參照

Bundler、CreateBundleOpts

BundleGraph parcel/packages/core/types/index.js:1401

包含 Bundle-s、Asset-s、Dependency-s、BundleGroup-s 的圖形

interface BundleGraph<TBundle: Bundle> {

  getAssetById(id: string): Asset,

根據 ID 擷取資產。

  getAssetPublicId(asset: Asset): string,

傳回資產的公開 (簡短) ID。

  getBundles(opts?: {|
    includeInline: boolean
  |}): Array<TBundle>,

傳回 bundle 圖形中 bundle 的清單。預設會排除內嵌 bundle。

  traverse<TContext>(visit: GraphVisitor<BundleGraphTraversable, TContext>, startAsset: ?Asset): ?TContext,

深度優先順序，橫跨 bundle 圖形中的資產和相依性。

  traverseBundles<TContext>(visit: GraphVisitor<TBundle, TContext>, startBundle: ?Bundle): ?TContext,

深度優先順序，橫跨 bundle 圖形中的所有 bundle，包括內嵌 bundle。

  getBundleGroupsContainingBundle(bundle: Bundle): Array<BundleGroup>,

傳回載入指定 bundle 的 bundle 群組清單。

  getBundlesInBundleGroup(bundleGroup: BundleGroup, opts?: {|
    includeInline: boolean
  |}): Array<TBundle>,

傳回在指定 bundle 群組中一起載入的 bundle 清單。

  getChildBundles(bundle: Bundle): Array<TBundle>,

傳回此 bundle 非同步載入的 bundle 清單。

  getParentBundles(bundle: Bundle): Array<TBundle>,

傳回非同步載入此 bundle 的 bundle 清單。

  hasParentBundleOfType(bundle: Bundle, type: string): boolean,

傳回 bundle 是否由指定類型的另一個 bundle 載入。

  getReferencedBundles(bundle: Bundle, opts?: {|
    recursive?: boolean,
    includeInline?: boolean,
  |}): Array<TBundle>,

傳回此 bundle 參照的 bundle 清單。預設會排除內嵌 bundle。

  getDependencies(asset: Asset): Array<Dependency>,

取得資產需要的相依性

  getIncomingDependencies(asset: Asset): Array<Dependency>,

取得需要資產的相依性

  getAssetWithDependency(dep: Dependency): ?Asset,

取得建立相依性的資產。

  isEntryBundleGroup(bundleGroup: BundleGroup): boolean,

傳回指定的 bundle 群組是否為入口。

  resolveAsyncDependency(dependency: Dependency, bundle: ?Bundle): ?({|
    type: 'bundle_group',
    value: BundleGroup,
  |} | {|
    type: 'asset',
    value: Asset,
  |}),

如果指定的相依性被排除或不是非同步，傳回未定義，否則傳回相依性解析到的 BundleGroup 或 Asset。

  isDependencySkipped(dependency: Dependency): boolean,

傳回相依性是否因沒有使用符號而被排除。

  getResolvedAsset(dependency: Dependency, bundle: ?Bundle): ?Asset,

傳回相依性解析的資產。如果給定一個套件，則偏好該套件中的資產。如果相依性被排除，則傳回 null。

  getReferencedBundle(dependency: Dependency, bundle: Bundle): ?TBundle,

傳回給定套件中的相依性所參考的套件（如果有的話）。

  getBundlesWithAsset(Asset): Array<TBundle>,

傳回包含給定資產的套件清單。

  getBundlesWithDependency(Dependency): Array<TBundle>,

傳回包含給定相依性的套件清單。

  isAssetReachableFromBundle(asset: Asset, bundle: Bundle): boolean,

傳回給定資產是否可從同層級或給定套件所有可能的祖先中取得。這表示資產可能從給定套件中排除。

  isAssetReferenced(bundle: Bundle, asset: Asset): boolean,

傳回資產是否在給定套件外部被參考。

  getSymbolResolution(asset: Asset, symbol: Symbol, boundary: ?Bundle): SymbolResolution,

解析 asset 的匯出 symbol 到來源，在離開 bundle 後的第一個資產處停止。symbol === null：退出（== 呼叫者應該執行 asset.exports[exportsSymbol]）symbol === undefined：找不到符號 symbol === false：略過
asset 匯出 symbol，嘗試找出對應變數存在的資產（解析重新匯出）。一旦離開 boundary（bundle.hasAsset(asset) === false），就停止遞迴解析，然後 result.symbol 為 undefined。

  getExportedSymbols(asset: Asset, boundary: ?Bundle): Array<ExportSymbolResolution>,

傳回資產匯出的符號清單，包括重新匯出。

  getUsedSymbols(Asset | Dependency): ?$ReadOnlySet<Symbol>,

傳回資產或相依性中由相依資產參考的符號清單。
如果符號傳播未執行（因此結果未知），則傳回 null。

  getEntryRoot(target: Target): FilePath,

傳回目標的入口資產的共用根目錄。

由下列項目參照

BuildSuccessEvent、BundleGroup、BundledProgressEvent、Bundler、BundlingProgressEvent、MutableBundleGraph、Namer、Optimizer、Packager、Runtime

BundleResult parcel/packages/core/types/index.js:1511

type BundleResult = {|

  +contents: Blob,

  +ast?: AST,

  +map?: ?SourceMap,

  +type?: string,

|}

由下列項目參照

Optimizer、Packager

Bundler parcel/packages/core/types/index.js:1574

將資產圖形轉換為 BundleGraph。
bundle 和 optimize 以串列方式執行，且在功能上相同。

type Bundler<ConfigType> = {|

  loadConfig?: ({|
    config: Config,
    options: PluginOptions,
    logger: PluginLogger,
  |}) => Promise<ConfigType> | ConfigType,

  bundle({|
    bundleGraph: MutableBundleGraph,
    config: ConfigType,
    options: PluginOptions,
    logger: PluginLogger,
  |}): Async<void>,

  optimize({|
    bundleGraph: MutableBundleGraph,
    config: ConfigType,
    options: PluginOptions,
    logger: PluginLogger,
  |}): Async<void>,

|}

由下列項目參照

MutableBundleGraph