0
# Bundle Analysis
1
2
Core functionality for analyzing JavaScript bundles through source maps, supporting multiple input formats and providing detailed size breakdowns.
3
4
## Capabilities
5
6
### Main Analysis Function
7
8
Analyzes bundle(s) and returns comprehensive exploration results with file size breakdowns.
9
10
```typescript { .api }
11
/**
12
* Analyze bundle(s) and return exploration results
13
* @param bundlesAndFileTokens - Bundle input (file paths, globs, Bundle objects, or arrays)
14
* @param options - Configuration options for analysis
15
* @returns Promise resolving to analysis results
16
*/
17
function explore(
18
bundlesAndFileTokens: BundlesAndFileTokens,
19
options?: ExploreOptions
20
): Promise<ExploreResult>;
21
22
type BundlesAndFileTokens = (Bundle | string)[] | Bundle | string;
23
```
24
25
**Usage Examples:**
26
27
```typescript
28
import { explore } from "source-map-explorer";
29
30
// Single file analysis
31
const result = await explore("dist/bundle.js");
32
33
// Multiple files using glob
34
const result = await explore("dist/*.js");
35
36
// Explicit bundle with separate source map
37
const result = await explore({
38
code: "dist/bundle.js",
39
map: "dist/bundle.js.map"
40
});
41
42
// Multiple bundles mixed formats
43
const result = await explore([
44
"dist/main.js",
45
{ code: "dist/chunk.js", map: "dist/chunk.js.map" },
46
"dist/vendor.*"
47
]);
48
49
// Using Buffer data
50
const codeBuffer = fs.readFileSync("bundle.js");
51
const result = await explore({ code: codeBuffer });
52
```
53
54
### Bundle Processing
55
56
The main explore function handles all bundle processing internally, including:
57
58
- Converting file tokens and glob patterns to Bundle objects
59
- Processing multiple input formats (file paths, Buffer data, Bundle objects)
60
- Analyzing each bundle individually
61
- Collecting and formatting results
62
63
All bundle processing logic is encapsulated within the explore function and does not expose separate utility functions for external use.
64
65
## Input Types
66
67
### Bundle Interface
68
69
```typescript { .api }
70
interface Bundle {
71
/** JavaScript code as file path or Buffer */
72
code: File;
73
/** Optional source map as file path or Buffer */
74
map?: File;
75
/** Optional coverage ranges for heat map visualization */
76
coverageRanges?: ColumnsRange[][];
77
}
78
79
type File = string | Buffer;
80
81
interface ColumnsRange {
82
/** First column index (inclusive) */
83
start: number;
84
/** Last column index (inclusive) */
85
end: number;
86
}
87
```
88
89
### Input Patterns
90
91
Source Map Explorer supports flexible input patterns:
92
93
- **File paths**: `"dist/bundle.js"` - Looks for inline source map or `bundle.js.map`
94
- **Glob patterns**: `"dist/*.js"` - Processes all matching files
95
- **Bundle objects**: `{ code: "path.js", map: "path.js.map" }` - Explicit source map
96
- **Buffer data**: `{ code: fs.readFileSync("bundle.js") }` - In-memory analysis
97
- **Mixed arrays**: Arrays combining any of the above formats
98
99
## Source Map Detection
100
101
The analysis engine automatically detects source maps through multiple methods:
102
103
1. **Inline source maps**: Embedded as data URLs in `sourceMappingURL` comments
104
2. **External source maps**: Referenced via `sourceMappingURL` comments pointing to `.map` files
105
3. **Conventional naming**: Automatically looks for `filename.js.map` when analyzing `filename.js`
106
4. **Explicit specification**: Use Bundle objects with explicit `map` property
107
108
**Examples:**
109
110
```typescript
111
// Inline source map (automatically detected)
112
const result = await explore("bundle-with-inline-map.js");
113
114
// External source map (automatically found)
115
const result = await explore("bundle.js"); // Looks for bundle.js.map
116
117
// Explicit source map
118
const result = await explore({
119
code: "bundle.js",
120
map: "custom-map-name.map"
121
});
122
123
// No source map comment, but map file exists
124
const result = await explore({
125
code: "no-comment.js",
126
map: "no-comment.js.map"
127
});
128
```
129
130
## Analysis Process
131
132
The bundle analysis follows these steps:
133
134
1. **Input Processing**: Convert file tokens and globs to Bundle objects
135
2. **Source Map Loading**: Detect and load source maps (inline or external)
136
3. **Size Calculation**: Calculate byte contributions for each original source file
137
4. **Coverage Integration**: Apply Chrome DevTools coverage data if provided
138
5. **Path Processing**: Clean and normalize file paths according to options
139
6. **Result Compilation**: Generate structured results with error handling
140
141
## Performance Considerations
142
143
- **Gzip Analysis**: Setting `gzip: true` calculates compressed sizes but disables unmapped byte calculation
144
- **Large Bundles**: Bundle analysis scales with source map complexity, not just file size
145
- **Memory Usage**: Buffer inputs keep data in memory; use file paths for large bundles when possible
146
- **Parallel Processing**: Multiple bundles are analyzed concurrently for better performance