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

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

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

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

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

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

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

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

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

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,
  hasDependency(Dependency): 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:934

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

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

type BundleGroup = {|
  +target: Target,
  +entryAssetId: string,
|}
Referenced by:
BundleGraph, MutableBundleGraph

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

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. 
  traverse<TContext>(GraphVisitor<BundlerBundleGraphTraversable, TContext>): ?TContext,
  traverseContents<TContext>(GraphVisitor<BundlerBundleGraphTraversable, TContext>): ?TContext,
}
Referenced by:
Bundler, CreateBundleOpts

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

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. 
  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 
  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:1066 

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

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

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