0
# Source Map Explorer
1

2
Source Map Explorer is a TypeScript library and command-line tool for analyzing JavaScript bundle size and composition through source maps. It creates interactive treemap visualizations that help developers understand which files and dependencies contribute most to their minified bundle size, enabling effective debugging of code bloat and optimization opportunities.
3

4
## Package Information
5

6
- **Package Name**: source-map-explorer
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install source-map-explorer`
10
- **CLI Installation**: `npm install -g source-map-explorer`
11

12
## Core Imports
13

14
```typescript
15
import { explore } from "source-map-explorer";
16
// or
17
import explore from "source-map-explorer";
18
```
19

20
For CommonJS:
21

22
```javascript
23
const { explore } = require("source-map-explorer");
24
// or
25
const explore = require("source-map-explorer").default;
26
```
27

28
## Basic Usage
29

30
```typescript
31
import { explore } from "source-map-explorer";
32

33
// Analyze a single bundle
34
const result = await explore("dist/bundle.js");
35

36
// Analyze bundle with explicit source map
37
const result = await explore({
38
  code: "dist/bundle.js",
39
  map: "dist/bundle.js.map"
40
});
41

42
// Analyze with options
43
const result = await explore("dist/bundle.js", {
44
  output: { format: "json" },
45
  onlyMapped: true
46
});
47

48
console.log(result.bundles[0].files);
49
// {
50
//   "src/main.js": { size: 2543 },
51
//   "node_modules/lodash/index.js": { size: 15234 },
52
//   "[unmapped]": { size: 156 }
53
// }
54
```
55

56
## Architecture
57

58
Source Map Explorer is built around several key components:
59

60
- **Core Analysis Engine**: Parses source maps and calculates file size contributions
61
- **Bundle Processing**: Handles multiple input formats (files, globs, buffers) and source map detection
62
- **Output Formatters**: Generates HTML treemaps, JSON data, and TSV reports
63
- **CLI Interface**: Command-line tool with extensive options for automation and CI/CD integration
64
- **Coverage Integration**: Chrome DevTools coverage support for heat map visualizations
65
- **Error Handling**: Comprehensive error reporting for source map issues and validation
66

67
## Capabilities
68

69
### Bundle Analysis
70

71
Core functionality for analyzing JavaScript bundles through source maps. Supports single files, glob patterns, and programmatic buffer inputs.
72

73
```typescript { .api }
74
function explore(
75
  bundlesAndFileTokens: BundlesAndFileTokens,
76
  options?: ExploreOptions
77
): Promise<ExploreResult>;
78

79
type BundlesAndFileTokens = (Bundle | string)[] | Bundle | string;
80

81
interface Bundle {
82
  code: File;
83
  map?: File;
84
  coverageRanges?: ColumnsRange[][];
85
}
86

87
type File = string | Buffer;
88
```
89

90
[Bundle Analysis](./bundle-analysis.md)
91

92
### Configuration Options
93

94
Comprehensive configuration system for customizing analysis behavior, output formats, and visualization options.
95

96
```typescript { .api }
97
interface ExploreOptions {
98
  onlyMapped?: boolean;
99
  excludeSourceMapComment?: boolean;
100
  output?: {
101
    format: 'json' | 'tsv' | 'html';
102
    filename?: string;
103
  };
104
  noRoot?: boolean;
105
  noBorderChecks?: boolean;
106
  replaceMap?: Record<string, string>;
107
  coverage?: string;
108
  gzip?: boolean;
109
  sort?: boolean;
110
}
111
```
112

113
[Configuration Options](./configuration.md)
114

115
### Analysis Results
116

117
Structured data format for bundle analysis results, including file size breakdowns, error handling, and formatted output.
118

119
```typescript { .api }
120
interface ExploreResult {
121
  bundles: ExploreBundleResult[];
122
  output?: string;
123
  errors: ExploreErrorResult[];
124
}
125

126
interface ExploreBundleResult {
127
  bundleName: string;
128
  files: Record<string, FileData>;
129
  mappedBytes: number;
130
  unmappedBytes?: number;
131
  eolBytes: number;
132
  sourceMapCommentBytes: number;
133
  totalBytes: number;
134
}
135
```
136

137
[Analysis Results](./analysis-results.md)
138

139
### Error Handling
140

141
Comprehensive error system with specific error codes for different failure scenarios and validation issues.
142

143
```typescript { .api }
144
class AppError extends Error {
145
  code?: ErrorCode;
146
  cause?: Error;
147
}
148

149
type ErrorCode = 
150
  | 'NoBundles'
151
  | 'NoSourceMap'
152
  | 'OneSourceSourceMap'
153
  | 'UnmappedBytes'
154
  | 'InvalidMappingLine'
155
  | 'InvalidMappingColumn'
156
  | 'CannotSaveFile'
157
  | 'CannotCreateTempFile'
158
  | 'CannotOpenTempFile'
159
  | 'CannotOpenCoverageFile'
160
  | 'NoCoverageMatches';
161
```
162

163
[Error Handling](./error-handling.md)
164

165
## Constants
166

167
```typescript { .api }
168
// Special file keys used in analysis results
169
const UNMAPPED_KEY = "[unmapped]";
170
const SOURCE_MAP_COMMENT_KEY = "[sourceMappingURL]";
171
const NO_SOURCE_KEY = "[no source]";
172
const EOL_KEY = "[EOLs]";
173
```
174

175
## Command Line Interface
176

177
The package provides both `source-map-explorer` and `sme` commands for command-line usage:
178

179
```bash
180
# Basic usage
181
source-map-explorer bundle.js
182

183
# Multiple bundles
184
source-map-explorer dist/*.js
185

186
# Output formats
187
source-map-explorer bundle.js --json result.json
188
source-map-explorer bundle.js --html result.html
189
source-map-explorer bundle.js --tsv result.tsv
190

191
# Options
192
source-map-explorer bundle.js --only-mapped --gzip --sort
193
```
194

195
The CLI supports all programmatic options through command-line flags and provides the same analysis capabilities as the programmatic API.