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 website/generate-api-docs/example.flow:747

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 website/generate-api-docs/example.flow:758

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

GraphTraversalCallback website/generate-api-docs/example.flow:771

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 propagate information from the parent to children (unlike a global variable).

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

BundleTraversable website/generate-api-docs/example.flow:780

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

BundlerBundleGraphTraversable website/generate-api-docs/example.flow:787

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

CreateBundleOpts website/generate-api-docs/example.flow:803

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.

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

SymbolResolution website/generate-api-docs/example.flow:832

Specifies a symbol in an asset 

type SymbolResolution = {|
  +asset: Asset,
  +exportSymbol: CodeSymbol | string,
  +symbol: void | null | CodeSymbol,
  +loc: ?SourceLocation,
|}
Referenced by:
ExportSymbolResolution, BundleGraph

ExportSymbolResolution website/generate-api-docs/example.flow:843 

type ExportSymbolResolution = {|
  ...SymbolResolution,
  +exportAs: CodeSymbol | string,
|}
Referenced by:
BundleGraph

Bundle website/generate-api-docs/example.flow:853

A Bundle (a collection of assets) 

interface Bundle {
  +id: string,
  +hashReference: string,
  +type: string,
  +env: Environment,
  +filePath: ?FilePath,
  +isEntry: ?boolean,
  +isInline: ?boolean,
  +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), the same as the last entry in getEntryAssets() 
  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:
NamedBundle, MutableBundleGraph, BundleGraph, Namer, Packager, PackagingProgressEvent, OptimizingProgressEvent

NamedBundle website/generate-api-docs/example.flow:886

A Bundle that got named by a Namer 

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

BundleGroup website/generate-api-docs/example.flow:896

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

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

MutableBundleGraph website/generate-api-docs/example.flow:906

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 VERIFY how?? 
  addBundleToBundleGroup(Bundle, BundleGroup): void,
  createAssetReference(Dependency, Asset): void,
FIXME 
  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>,
FIXME a dependency can have multiple child nodes? 
  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,
FIME difference to traverseContents? 
  traverseContents<TContext>(GraphVisitor<BundlerBundleGraphTraversable, TContext>): ?TContext,
FIXME 
}
Referenced by:
CreateBundleOpts, Bundler

BundleGraph website/generate-api-docs/example.flow:939

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

interface BundleGraph<TBundle: Bundle> {
  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>,
See BundleGroup 
  getReferencedBundles(bundle: Bundle): Array<TBundle>,
Bundles that are referenced (by filename) 
  getDependencies(asset: Asset): Array<Dependency>,
Get the dependencies of the asset 
  getIncomingDependencies(asset: Asset): Array<Dependency>,
Get the dependencies that require the asset 
  resolveExternalDependency(dependency: Dependency, bundle: ?Bundle): ?({|
    type: "bundle_group",
    value: BundleGroup,
  |} | {|
    type: "asset",
    value: Asset,
  |}),
resolveExternalDependency 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. 
  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,
Whether the asset is referenced (the "references" edge)FIXME how? url/filename? 
  isAssetReferencedByDependant(bundle: Bundle, asset: Asset): boolean,
Whether the asset is referenced by URL which could cause an import. 
  hasParentBundleOfType(bundle: Bundle, type: string): boolean,
  resolveSymbol(asset: Asset, symbol: CodeSymbol, 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:
BundleGroup, MutableBundleGraph, Bundler, Namer, Runtime, Packager, BundlingProgressEvent, BuildSuccessEvent

BundleResult website/generate-api-docs/example.flow:1003 

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

Bundler website/generate-api-docs/example.flow:1027

Turns an asset graph into a BundleGraph.
The two methods just run in series and are functionally identitical. 

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