Bundler

A plugin type: Turns an asset graph into a bundle graph

The Bundler API is experimental and therefore subject to change, even between minor updates.

Bundlers accept the entire asset graph and modify it to add bundle nodes that group the assets into output bundles.

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

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

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

Relevant API

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

Used to control a traversal

interface TraversalActions {
  skipChildren(): void,

Skip the current node's children and continue the traversal if there are other nodes in the queue.

  stop(): void,

Stop the traversal

}
Referenced by:
GraphTraversalCallback

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

Essentially GraphTraversalCallback, but allows adding specific node enter and exit callbacks.

Type
type GraphVisitor<TNode, TContext> = GraphTraversalCallback<TNode, TContext> | {|
  enter?: GraphTraversalCallback<TNode, TContext>,
  exit?: GraphTraversalCallback<TNode, TContext>,
|};
Referenced by:
Bundle, BundleGraph

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

A generic callback for graph traversals

Parameter Descriptions
  • context: The parent node's return value is passed as a parameter to the children's callback. This can be used to forward information from the parent to children in a DFS (unlike a global variable).

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

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

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

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

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

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

Options for MutableBundleGraph's createBundle.
If an entryAsset is provided, uniqueKey (for the bundle id), type, and env will be inferred from the entryAsset.
If an entryAsset is not provided, uniqueKey (for the bundle id), type, and env must be provided.
isSplittable defaults to entryAsset.isSplittable or false

Type
type CreateBundleOpts = {|
  +entryAsset: Asset,
  +target: Target,
  +needsStableName?: ?boolean,
|} | {|
  +type: string,
  +env: Environment,
  +uniqueKey: string,
  +target: Target,
  +needsStableName?: ?boolean,
  +isInline?: ?boolean,
  +isSplittable?: ?boolean,
  +pipeline?: ?string,
|};
Referenced by:
MutableBundleGraph

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

A Bundle (a collection of assets) 

interface Bundle {
  +id: string,

The bundle id.

  +type: string,

The type of the bundle.

  +env: Environment,

The environment of the bundle.

  +target: Target,

The bundle's target.

  +needsStableName: ?boolean,

Indicates that the bundle's file name should be stable over time, even when the content of the bundle changes. This is useful for entries that a user would manually enter the URL for, as well as for things like service workers or RSS feeds, where the URL must remain consistent over time.

  +isInline: ?boolean,

Whether this bundle should be inlined into the parent bundle(s),

  +isSplittable: ?boolean,

Whether the bundle can be split. If false, then all dependencies of the bundle will be kept internal to the bundle, rather than referring to other bundles. This may result in assets being duplicated between multiple bundles, but can be useful for things like server side rendering.

  +hashReference: string,

A placeholder for the bundle's content hash that can be used in the bundle's name or the contents of another bundle. Hash references are replaced with a content hash of the bundle after packaging and optimizing.

  getEntryAssets(): Array<Asset>,

Returns the assets that are executed immediately when the bundle is loaded. Some bundles may not have any entry assets, for example, shared bundles.

  getMainEntry(): ?Asset,

Returns the main entry of the bundle, which will provide the bundle's exports. Some bundles do not have a main entry, for example, shared bundles.

  hasAsset(Asset): boolean,

Returns whether the bundle includes the given asset.

  hasDependency(Dependency): boolean,

Returns whether the bundle includes the given dependency.

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

Traverses the assets in the bundle.

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

Traverses assets and dependencies in the bundle.

}
Referenced by:
BundleGraph, MutableBundleGraph, NamedBundle, Namer, OptimizingProgressEvent, Packager, PackagingProgressEvent

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

A Bundle that got named by a Namer

interface NamedBundle extends Bundle {
  +publicId: string,

A shortened version of the bundle id that is used to refer to the bundle at runtime.

  +name: string,

The bundle's name. This is a file path relative to the bundle's target directory. The bundle name may include a hash reference, but not the final content hash.

  +displayName: string,

A version of the bundle's name with hash references removed for display.

}
Referenced by:
BuildSuccessEvent, Optimizer, OptimizingProgressEvent, PackagedBundle, Packager, PackagingProgressEvent, Runtime

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

A collection of sibling bundles (which are stored in the BundleGraph) that should be loaded together (in order).

type BundleGroup = {|
  +target: Target,

The target of the bundle group.

  +entryAssetId: string,

The id of the entry asset in the bundle group, which is executed immediately when the bundle group is loaded.

|}
Referenced by:
BundleGraph, MutableBundleGraph

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

A BundleGraph in the Bundler that can be modified

interface MutableBundleGraph extends BundleGraph<Bundle> {
  addAssetGraphToBundle(Asset, Bundle, shouldSkipDependency?: (Dependency) => boolean): void,

Add asset and all child nodes to the bundle.

  addEntryToBundle(Asset, Bundle, shouldSkipDependency?: (Dependency) => boolean): void,
  addBundleToBundleGroup(Bundle, BundleGroup): void,
  createAssetReference(Dependency, Asset, Bundle): void,
  createBundleReference(Bundle, Bundle): void,
  createBundle(CreateBundleOpts): Bundle,
  createBundleGroup(Dependency, Target): BundleGroup,

Turns an edge (Dependency -> Asset-s) into (Dependency -> BundleGroup -> Asset-s)

  getDependencyAssets(Dependency): Array<Asset>,
  getParentBundlesOfBundleGroup(BundleGroup): Array<Bundle>,
  getTotalSize(Asset): number,
  removeAssetGraphFromBundle(Asset, Bundle): void,

Remove all "contains" edges from the bundle to the nodes in the asset's subgraph.

  removeBundleGroup(bundleGroup: BundleGroup): void,
  internalizeAsyncDependency(bundle: Bundle, dependency: Dependency): void,

Turns a dependency to a different bundle into a dependency to an asset inside bundle.

}
Referenced by:
Bundler, CreateBundleOpts

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

A Graph that contains Bundle-s, Asset-s, Dependency-s, BundleGroup-s

interface BundleGraph<TBundle: Bundle> {
  getAssetById(id: string): Asset,
  getAssetPublicId(asset: Asset): string,
  getBundles(): Array<TBundle>,
  getBundleGroupsContainingBundle(bundle: Bundle): Array<BundleGroup>,
  getBundlesInBundleGroup(bundleGroup: BundleGroup): Array<TBundle>,
  getChildBundles(bundle: Bundle): Array<TBundle>,

Child bundles are Bundles that might be loaded by an asset in the bundle

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

Bundles that are referenced (by filename)

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

Get the dependencies that the asset requires

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

Get the dependencies that require the asset

  getAssetWithDependency(dep: Dependency): ?Asset,

Get the asset that created the dependency.

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

Returns undefined if the specified dependency was excluded or wasn't async and otherwise the BundleGroup or Asset that the dependency resolves to.

  isDependencySkipped(dependency: Dependency): boolean,

If a dependency was excluded since it's unused based on symbol data.

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

Find out which asset the dependency resolved to.

  getReferencedBundle(dependency: Dependency, bundle: Bundle): ?TBundle,
  findBundlesWithAsset(Asset): Array<TBundle>,
  findBundlesWithDependency(Dependency): Array<TBundle>,
  isAssetReachableFromBundle(asset: Asset, bundle: Bundle): boolean,

Whether the asset is already included in a compatible (regarding EnvironmentContext) parent bundle.

  findReachableBundleWithAsset(bundle: Bundle, asset: Asset): ?TBundle,
  isAssetReferencedByDependant(bundle: Bundle, asset: Asset): boolean,
  hasParentBundleOfType(bundle: Bundle, type: string): boolean,
  resolveSymbol(asset: Asset, symbol: Symbol, boundary: ?Bundle): SymbolResolution,

Resolve the export symbol of asset to the source, stopping at the first asset after leaving bundle. symbol === null: bailout (== caller should do asset.exports[exportsSymbol]) symbol === undefined: symbol not found symbol === false: skipped
asset exports symbol, try to find the asset where the corresponding variable lives (resolves re-exports). Stop resolving transitively once boundary was left (bundle.hasAsset(asset) === false), then result.symbol is undefined.

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

Gets the symbols that are (transivitely) exported by the asset

  traverse<TContext>(GraphVisitor<BundleGraphTraversable, TContext>): ?TContext,
  traverseBundles<TContext>(visit: GraphVisitor<TBundle, TContext>, startBundle: ?Bundle): ?TContext,
  getUsedSymbols(Asset | Dependency): $ReadOnlySet<Symbol>,
}
Referenced by:
BuildSuccessEvent, BundleGroup, Bundler, BundlingProgressEvent, MutableBundleGraph, Namer, Optimizer, Packager, Runtime

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

type BundleResult = {|
  +contents: Blob,
  +ast?: AST,
  +map?: ?SourceMap,
  +type?: string,
|}
Referenced by:
Optimizer, Packager

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

Turns an asset graph into a BundleGraph.
bundle and optimize run in series and are functionally identitical.

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>,
|}
Referenced by:
MutableBundleGraph