Bundler

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

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:737

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:748

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, MutableBundleGraph

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

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:770

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

BundlerBundleGraphTraversable parcel/packages/core/types/index.js:777

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

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

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 = {|
  +uniqueKey?: string,
  +entryAsset: Asset,
  +target: Target,
  +isEntry?: ?boolean,
  +isInline?: ?boolean,
  +isSplittable?: ?boolean,
  +type?: ?string,
  +env?: ?Environment,
  +pipeline?: ?string,
|} | {|
  +uniqueKey: string,
  +entryAsset?: Asset,
  +target: Target,
  +isEntry?: ?boolean,
  +isInline?: ?boolean,
  +isSplittable?: ?boolean,
  +type: string,
  +env: Environment,
  +pipeline?: ?string,
|};
Referenced by:
MutableBundleGraph

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

A Bundle (a collection of assets)

interface BundleΒ {
  +id: string,
  +hashReference: string,
Whether this value is inside filePath it will be replace with the real hash at the end.
  +type: string,
  +env: Environment,
  +filePath: ?FilePath,
The output filespath (if not inline), can contain hashReference before the optimizer ran.
  +isEntry: ?boolean,
Whether this is an entry (e.g. should not be hashed).
  +isInline: ?boolean,
Whether this bundle should be inlined into the parent bundle(s),
  +isSplittable: ?boolean,
  +target: Target,
  +stats: Stats,
  getEntryAssets(): Array<Asset>,
Assets that run when the bundle is loaded (e.g. runtimes could be added). VERIFY
  getMainEntry(): ?Asset,
The actual entry (which won't be a runtime).
  hasAsset(Asset): boolean,
  traverseAssets<TContext>(visit: GraphVisitor<Asset, TContext>): ?TContext,
Traverses the assets in the bundle.
  traverse<TContext>(visit: GraphVisitor<BundleTraversable, TContext>): ?TContext,
Traverses assets and dependencies (see BundleTraversable).
}
Referenced by:
BundleGraph, MutableBundleGraph, NamedBundle, Namer, OptimizingProgressEvent, Packager, PackagingProgressEvent

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

A Bundle that got named by a Namer

interface NamedBundle extends BundleΒ {
  +publicId: string,
  +filePath: FilePath,
  +name: string,
  +displayName: string,
}
Referenced by:
BuildSuccessEvent, Optimizer, OptimizingProgressEvent, Packager, PackagingProgressEvent, Runtime

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

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

type BundleGroupΒ = {|
  target: Target,
  entryAssetId: string,
  bundleIds: Array<string>,
|}
Referenced by:
BundleGraph, MutableBundleGraph

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

A BundleGraph in the Bundler that can be modified

interface MutableBundleGraph extends BundleGraph<Bundle>Β {
  addAssetGraphToBundle(Asset, Bundle): void,
Add asset and all child nodes to the bundle.
  addEntryToBundle(Asset, Bundle): void,
  addBundleToBundleGroup(Bundle, BundleGroup): void,
  createAssetReference(Dependency, Asset): 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.
  traverse<TContext>(GraphVisitor<BundlerBundleGraphTraversable, TContext>): ?TContext,
  traverseContents<TContext>(GraphVisitor<BundlerBundleGraphTraversable, TContext>): ?TContext,
}
Referenced by:
Bundler, CreateBundleOpts

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

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>,
  getSiblingBundles(bundle: Bundle): Array<TBundle>,
  getReferencedBundles(bundle: Bundle): Array<TBundle>,
Bundles that are referenced (by filename)
  getDependencies(asset: Asset): Array<Dependency>,
Get the dependencies that require the asset
  getIncomingDependencies(asset: Asset): Array<Dependency>,
Get the dependencies that require the asset
  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.
  isDependencyDeferred(dependency: Dependency): boolean,
  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,
  isAssetReferenced(asset: Asset): boolean,
  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
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): Array<ExportSymbolResolution>,
Gets the symbols that are (transivitely) exported by the asset
  traverseBundles<TContext>(visit: GraphVisitor<TBundle, TContext>, startBundle: ?Bundle): ?TContext,
}
Referenced by:
BuildSuccessEvent, BundleGroup, Bundler, BundlingProgressEvent, MutableBundleGraph, Namer, Optimizer, Packager, Runtime

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

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

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

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

type BundlerΒ = {|
  loadConfig?: ({|
    options: PluginOptions,
    logger: PluginLogger,
  |}) => Async<ConfigOutput>,
  bundle({|
    bundleGraph: MutableBundleGraph,
    config: ?ConfigResult,
    options: PluginOptions,
    logger: PluginLogger,
  |}): Async<void>,
  optimize({|
    bundleGraph: MutableBundleGraph,
    config: ?ConfigResult,
    options: PluginOptions,
    logger: PluginLogger,
  |}): Async<void>,
|}
Referenced by:
MutableBundleGraph