0
# Bundle System
1

2
Bundle creation, optimization, and graph traversal for the final build output, including bundle groups, dependency resolution, and symbol management.
3

4
## Capabilities
5

6
### Bundle Interface
7

8
Core bundle representation with metadata and asset management.
9

10
```typescript { .api }
11
/**
12
 * Core bundle interface representing a collection of assets
13
 */
14
interface Bundle {
15
  /** Unique bundle identifier */
16
  readonly id: string;
17
  /** Bundle content type (e.g., 'js', 'css', 'html') */
18
  readonly type: string;
19
  /** Target environment for this bundle */
20
  readonly env: Environment;
21
  /** Build target configuration */
22
  readonly target: Target;
23
  /** Whether this bundle needs a stable name across builds */
24
  readonly needsStableName: ?boolean;
25
  /** Bundle loading behavior */
26
  readonly bundleBehavior: ?BundleBehavior;
27
  /** Whether this bundle can be split into smaller bundles */
28
  readonly isSplittable: ?boolean;
29
  /** Hash reference placeholder for the bundle content */
30
  readonly hashReference: string;
31
  
32
  /** Get all entry assets for this bundle */
33
  getEntryAssets(): Array<Asset>;
34
  /** Get the main entry asset */
35
  getMainEntry(): ?Asset;
36
  /** Check if bundle contains a specific asset */
37
  hasAsset(asset: Asset): boolean;
38
  /** Check if bundle contains a specific dependency */
39
  hasDependency(dependency: Dependency): boolean;
40
  /** Traverse all assets in the bundle */
41
  traverseAssets<TContext>(
42
    visit: GraphVisitor<Asset, TContext>, 
43
    startAsset?: Asset
44
  ): ?TContext;
45
  /** Traverse assets and dependencies in the bundle */
46
  traverse<TContext>(visit: GraphVisitor<BundleTraversable, TContext>): ?TContext;
47
  /** Get content hash for the bundle */
48
  getContentHash(): string;
49
}
50

51
/**
52
 * Bundle with naming information
53
 */
54
interface NamedBundle extends Bundle {
55
  /** Public bundle identifier */
56
  readonly publicId: string;
57
  /** Bundle file name */
58
  readonly name: string;
59
  /** Display name for reporting */
60
  readonly displayName: string;
61
}
62

63
/**
64
 * Final packaged bundle with file information
65
 */
66
interface PackagedBundle extends NamedBundle {
67
  /** File path of the packaged bundle */
68
  readonly filePath: FilePath;
69
  /** Bundle file statistics */
70
  readonly stats: Stats;
71
}
72
```
73

74
### Bundle Graph
75

76
Complete bundle graph operations for dependency resolution and traversal.
77

78
```typescript { .api }
79
/**
80
 * Bundle graph interface for querying bundle relationships
81
 */
82
interface BundleGraph<TBundle: Bundle = Bundle> {
83
  /** Get all bundles in the graph */
84
  getBundles(): Array<TBundle>;
85
  /** Get child bundles (async dependencies) */
86
  getChildBundles(bundle: TBundle): Array<TBundle>;
87
  /** Get sibling bundles (same bundle group) */
88
  getSiblingBundles(bundle: TBundle): Array<TBundle>;
89
  /** Get bundles that contain a specific asset */
90
  getBundlesWithAsset(asset: Asset): Array<TBundle>;
91
  /** Get bundles that depend on a specific bundle */
92
  getParentBundles(bundle: TBundle): Array<TBundle>;
93
  
94
  /** Resolve async dependency to bundle and asset */
95
  resolveAsyncDependency(
96
    dependency: Dependency, 
97
    bundle: ?TBundle
98
  ): ?{bundle: TBundle, asset: Asset};
99
  
100
  /** Get dependency resolution between bundles */
101
  getDependencyResolution(
102
    dependency: Dependency, 
103
    bundle: ?TBundle
104
  ): ?{bundleGraph: BundleGraph<TBundle>, bundle: ?TBundle, asset: Asset};
105
  
106
  /** Get referenced bundles from a bundle */
107
  getReferencedBundles(bundle: TBundle): Array<TBundle>;
108
  
109
  /** Traverse bundles in the graph */
110
  traverseBundles<TContext>(
111
    visit: GraphVisitor<TBundle, TContext>,
112
    startBundle?: TBundle
113
  ): ?TContext;
114
  
115
  /** Get asset by ID */
116
  getAssetById(id: string): Asset;
117
  /** Get public ID for an asset */
118
  getAssetPublicId(asset: Asset): string;
119
  
120
  /** Get symbol resolution for an asset */
121
  getSymbolResolution(
122
    asset: Asset,
123
    symbol: Symbol,
124
    boundary: ?Bundle
125
  ): SymbolResolution;
126
  
127
  /** Get exported symbols from an asset */
128
  getExportedSymbols(asset: Asset, boundary: ?Bundle): Array<ExportSymbolResolution>;
129
  /** Get symbols used by an asset */
130
  getUsedSymbols(asset: Asset): ?Array<Symbol>;
131
  
132
  /** Check if asset is referenced by a bundle */
133
  isAssetReferenced(bundle: TBundle, asset: Asset): boolean;
134
  /** Check if asset is reachable from entry bundles */
135
  isAssetReachableFromEntry(asset: Asset): boolean;
136
  
137
  /** Get content hash for a bundle */
138
  getContentHash(bundle: TBundle): string;
139
}
140

141
/**
142
 * Mutable bundle graph for bundler plugins
143
 */
144
interface MutableBundleGraph extends BundleGraph<Bundle> {
145
  /** Add asset to a bundle */
146
  addAssetToBundle(asset: Asset, bundle: Bundle): void;
147
  /** Add entry asset to a bundle */
148
  addEntryToBundle(asset: Asset, bundle: Bundle): void;
149
  /** Create a new bundle */
150
  createBundle(opts: CreateBundleOpts): Bundle;
151
  /** Create a new bundle group */
152
  createBundleGroup(dependency: Dependency, target: Target): BundleGroup;
153
  /** Remove asset sub-graph from bundle */
154
  removeAssetGraphFromBundle(asset: Asset, bundle: Bundle): void;
155
  /** Remove bundle from graph */
156
  removeBundle(bundle: Bundle): void;
157
  /** Add dependency between bundles */
158
  addBundleToBundleGroup(bundle: Bundle, bundleGroup: BundleGroup): void;
159
  /** Create asset reference between bundles */
160
  createAssetReference(dependency: Dependency, asset: Asset, bundle: Bundle): void;
161
  /** Find bundles in the same bundle group */
162
  findBundlesWithDependency(dependency: Dependency): Array<Bundle>;
163
}
164
```
165

166
### Bundle Groups
167

168
Bundle group management for organizing related bundles.
169

170
```typescript { .api }
171
/**
172
 * Bundle group representing sibling bundles
173
 */
174
interface BundleGroup {
175
  /** Target environment */
176
  target: Target;
177
  /** Entry dependency that created this group */
178
  entryAsset: Asset;
179
  /** All bundles in this group */
180
  bundles: Array<Bundle>;
181
}
182
```
183

184
### Bundle Creation
185

186
Options and utilities for creating bundles.
187

188
```typescript { .api }
189
/**
190
 * Options for creating a new bundle
191
 */
192
interface CreateBundleOpts {
193
  /** Entry asset for the bundle */
194
  entryAsset?: Asset;
195
  /** Target environment */
196
  target: Target;
197
  /** Bundle content type */
198
  type?: string;
199
  /** Whether bundle needs stable name */
200
  needsStableName?: boolean;
201
  /** Bundle behavior */
202
  bundleBehavior?: BundleBehavior;
203
  /** Whether bundle is splittable */
204
  isSplittable?: boolean;
205
  /** Whether bundle is an entry point */
206
  isEntry?: boolean;
207
  /** Whether bundle should be inlined */
208
  isInline?: boolean;
209
  /** Asset processing pipeline */
210
  pipeline?: string;
211
  /** Bundle environment */
212
  env?: Environment;
213
}
214
```
215

216
### Symbol Resolution
217

218
Symbol resolution and export management across bundles.
219

220
```typescript { .api }
221
/**
222
 * Symbol resolution result
223
 */
224
interface SymbolResolution {
225
  /** Resolved asset containing the symbol */
226
  asset: Asset;
227
  /** Exported symbol name */
228
  exportSymbol: Symbol;
229
  /** Local symbol name in the asset */
230
  symbol: ?Symbol;
231
  /** Location in source code */
232
  loc: ?SourceLocation;
233
}
234

235
/**
236
 * Export symbol resolution with re-export information  
237
 */
238
interface ExportSymbolResolution {
239
  /** Exported symbol name */
240
  exportSymbol: Symbol;
241
  /** Local symbol name */
242
  symbol: ?Symbol;
243
  /** Source asset if re-exported */
244
  asset: ?Asset;
245
  /** Location in source code */
246
  loc: ?SourceLocation;
247
}
248
```
249

250
### Bundle Traversal
251

252
Graph traversal utilities for bundles and assets.
253

254
```typescript { .api }
255
/**
256
 * Bundle traversal node types
257
 */
258
type BundleTraversable = Asset | Bundle | Dependency;
259

260
/**
261
 * Graph visitor for bundle traversal
262
 */
263
interface GraphVisitor<TNode, TContext> {
264
  (node: TNode, context: TContext, actions: TraversalActions): ?TContext;
265
}
266

267
/**
268
 * Traversal control actions
269
 */
270
interface TraversalActions {
271
  /** Skip visiting children of current node */
272
  skipChildren(): void;
273
  /** Stop traversal entirely */
274
  stop(): void;
275
}
276
```
277

278
### Bundle Results
279

280
Bundle processing results and metadata.
281

282
```typescript { .api }
283
/**
284
 * Bundle processing result
285
 */
286
interface BundleResult {
287
  /** Bundle contents */
288
  contents: Blob;
289
  /** Source map */
290
  map?: SourceMap;
291
  /** Bundle metadata */
292
  type?: string;
293
}
294
```
295

296
**Usage Examples:**
297

298
```typescript
299
import type { 
300
  BundleGraph, 
301
  MutableBundleGraph, 
302
  Bundle, 
303
  CreateBundleOpts 
304
} from '@parcel/types';
305

306
// Query bundle relationships
307
function analyzeBundles(bundleGraph: BundleGraph) {
308
  const bundles = bundleGraph.getBundles();
309
  
310
  for (const bundle of bundles) {
311
    console.log(`Bundle: ${bundle.name}`);
312
    
313
    // Get child bundles (async dependencies)
314
    const children = bundleGraph.getChildBundles(bundle);
315
    console.log(`  Children: ${children.map(b => b.name).join(', ')}`);
316
    
317
    // Get sibling bundles
318
    const siblings = bundleGraph.getSiblingBundles(bundle);
319
    console.log(`  Siblings: ${siblings.map(b => b.name).join(', ')}`);
320
    
321
    // Check bundle contents
322
    bundle.traverseAssets((asset) => {
323
      console.log(`  Asset: ${asset.filePath}`);
324
    });
325
  }
326
}
327

328
// Create bundles in a bundler plugin
329
function createCustomBundles(bundleGraph: MutableBundleGraph) {
330
  // Create a CSS bundle
331
  const cssBundle = bundleGraph.createBundle({
332
    type: 'css',
333
    target: getCurrentTarget(),
334
    needsStableName: true
335
  });
336
  
337
  // Find CSS assets and add them to the bundle
338
  const allBundles = bundleGraph.getBundles();
339
  for (const bundle of allBundles) {
340
    bundle.traverseAssets((asset) => {
341
      if (asset.type === 'css') {
342
        bundleGraph.addAssetToBundle(asset, cssBundle);
343
      }
344
    });
345
  }
346
}
347

348
// Resolve symbols across bundles
349
function resolveExports(bundleGraph: BundleGraph, asset: Asset) {
350
  // Get all exported symbols
351
  const exports = bundleGraph.getExportedSymbols(asset);
352
  
353
  for (const exportRes of exports) {
354
    console.log(`Export: ${exportRes.exportSymbol}`);
355
    
356
    if (exportRes.asset) {
357
      console.log(`  Re-exported from: ${exportRes.asset.filePath}`);
358
    }
359
  }
360
  
361
  // Resolve a specific symbol
362
  const resolution = bundleGraph.getSymbolResolution(asset, 'myExport');
363
  if (resolution) {
364
    console.log(`Symbol 'myExport' resolved to ${resolution.asset.filePath}:${resolution.symbol}`);
365
  }
366
}
367

368
// Traverse bundle graph
369
function traverseBundleGraph(bundleGraph: BundleGraph) {
370
  bundleGraph.traverseBundles((bundle, context, actions) => {
371
    if (bundle.type === 'js') {
372
      console.log(`Processing JS bundle: ${bundle.name}`);
373
      
374
      // Skip children if this is a worker bundle
375
      if (bundle.env.context === 'web-worker') {
376
        actions.skipChildren();
377
      }
378
    }
379
  });
380
}
381
```