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

Used to control a traversal

type 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:1126

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

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

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

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

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

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

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,
  +bundleBehavior?: ?BundleBehavior,
|}
| {|
  +type: string,
  +env: Environment,
  +uniqueKey: string,
  +target: Target,
  +needsStableName?: ?boolean,
  +bundleBehavior?: ?BundleBehavior,
  +isSplittable?: ?boolean,
  +pipeline?: ?string,
|};
Referenced by:
MutableBundleGraph

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

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,

Assets that run when the bundle is loaded (e.g. runtimes could be added). VERIFY

  +bundleBehavior: ?BundleBehavior,

Controls the behavior of the bundle. to determine when the bundle is loaded.

  • inline: Inline bundles are not written to a separate file, but embedded into the parent bundle.
  • isolated: The bundle will be isolated from its parents. Shared assets will be duplicated.
  +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>, startAsset?: Asset): ?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:1318

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, BundledProgressEvent, Optimizer, OptimizingProgressEvent, PackagedBundle, Packager, PackagingProgressEvent, Runtime

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

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

interface 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:1353

A BundleGraph in the Bundler that can be modified

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

Add asset and all child nodes to the bundle.

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

Adds an asset as an entry to a bundle. Entry assets are executed immediately when the bundle is loaded.

  addBundleToBundleGroup(Bundle, BundleGroup): void,

Adds the Bundle to the BundleGroup, loading it along with others in the group

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

Get Bundles that load this bundle asynchronously.

  getTotalSize(Asset): number,
  removeAssetGraphFromBundle(Asset, Bundle): void,

Recursively removes an asset and its dependencies from a bundle. Stops at bundle group boundaries.

  removeBundleGroup(bundleGroup: BundleGroup): void,

Removes a BundleGroup from the graph. If any of the group's Bundle-s no longer exist in the graph, those are removed as well.

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

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

interface BundleGraph<TBundle: Bundle> {
  getAssetById(id: string): Asset,

Retrieves an asset by id.

  getAssetPublicId(asset: Asset): string,

Returns the public (short) id for an asset.

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

Returns a list of bundles in the bundle graph. By default, inline bundles are excluded.

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

Traverses the assets and dependencies in the bundle graph, in depth first order.

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

Traverses all bundles in the bundle graph, including inline bundles, in depth first order.

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

Returns a list of bundle groups that load the given bundle.

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

Returns a list of bundles that load together in the given bundle group.

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

Returns a list of bundles that this bundle loads asynchronously.

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

Returns a list of bundles that load this bundle asynchronously.

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

Returns whether the bundle was loaded by another bundle of the given type.

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

Returns a list of bundles that are referenced by this bundle. By default, inline bundles are excluded.

  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,

Returns whether the given bundle group is an entry.

  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,

Returns whether a dependency was excluded because it had no used symbols.

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

Returns the asset that the dependency resolved to. If a bundle is given, assets in that bundle are preferred. Returns null if the dependency was excluded.

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

Returns the bundle that a dependency in a given bundle references, if any.

  getBundlesWithAsset(Asset): Array<TBundle>,

Returns a list of bundles that contain the given asset.

  getBundlesWithDependency(Dependency): Array<TBundle>,

Returns a list of bundles that contain the given dependency.

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

Returns whether the given asset is reachable in a sibling, or all possible ancestries of the given bundle. This indicates that the asset may be excluded from the given bundle.

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

Returns whether an asset is referenced outside the given bundle.

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

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

Returns a list of symbols that are exported by the asset, including re-exports.

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

Returns a list of symbols from an asset or dependency that are referenced by a dependent asset.
Returns null if symbol propagation didn't run (so the result is unknown).

  getEntryRoot(target: Target): FilePath,

Returns the common root directory for the entry assets of a target.

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

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

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