0
# Configuration Options
1

2
Comprehensive configuration system for customizing analysis behavior, output formats, and visualization options.
3

4
## Capabilities
5

6
### Explore Options Interface
7

8
Complete configuration interface for the explore function.
9

10
```typescript { .api }
11
interface ExploreOptions {
12
  /** Exclude "unmapped" bytes from the output */
13
  onlyMapped?: boolean;
14
  /** Exclude source map comment size from output */
15
  excludeSourceMapComment?: boolean;
16
  /** Output result as a string */
17
  output?: {
18
    format: OutputFormat;
19
    /** Filename to save output to */
20
    filename?: string;
21
  };
22
  /** Disable removing prefix shared by all sources */
23
  noRoot?: boolean;
24
  /** Disable invalid mapping column/line checks */
25
  noBorderChecks?: boolean;
26
  /** Replace "this" by "that" map */
27
  replaceMap?: ReplaceMap;
28
  /** Path to Chrome code coverage JSON export */
29
  coverage?: string;
30
  /** Calculate gzip size. Setting it to true will also set onlyMapped to true */
31
  gzip?: boolean;
32
  /** Sort filenames */
33
  sort?: boolean;
34
}
35

36
type OutputFormat = 'json' | 'tsv' | 'html';
37
type ReplaceMap = Record<string, string>;
38
```
39

40
## Configuration Categories
41

42
### Output Control Options
43

44
Options controlling how results are formatted and where they're saved.
45

46
```typescript { .api }
47
interface OutputOptions {
48
  format: OutputFormat;
49
  filename?: string;
50
}
51
```
52

53
**Usage Examples:**
54

55
```typescript
56
import { explore } from "source-map-explorer";
57

58
// JSON output to console
59
const result = await explore("bundle.js", {
60
  output: { format: "json" }
61
});
62

63
// Save HTML visualization to file
64
const result = await explore("bundle.js", {
65
  output: { format: "html", filename: "analysis.html" }
66
});
67

68
// TSV output for spreadsheet import
69
const result = await explore("bundle.js", {
70
  output: { format: "tsv", filename: "sizes.tsv" }
71
});
72
```
73

74
### Size Calculation Options
75

76
Control which bytes are included in size calculations.
77

78
```typescript { .api }
79
// Include/exclude unmapped bytes
80
onlyMapped?: boolean;
81

82
// Include/exclude source map comment bytes
83
excludeSourceMapComment?: boolean;
84

85
// Calculate gzip compressed sizes
86
gzip?: boolean;
87
```
88

89
**Usage Examples:**
90

91
```typescript
92
// Exclude unmapped bytes for cleaner results
93
const result = await explore("bundle.js", {
94
  onlyMapped: true
95
});
96

97
// Exclude source map comment from totals
98
const result = await explore("bundle.js", {
99
  excludeSourceMapComment: true
100
});
101

102
// Calculate gzip sizes (automatically sets onlyMapped: true)
103
const result = await explore("bundle.js", {
104
  gzip: true
105
});
106

107
// Combined size options
108
const result = await explore("bundle.js", {
109
  onlyMapped: true,
110
  excludeSourceMapComment: true,
111
  gzip: false
112
});
113
```
114

115
### Path Processing Options
116

117
Control how file paths are processed and displayed in results.
118

119
```typescript { .api }
120
// Disable common path prefix removal
121
noRoot?: boolean;
122

123
// File path string replacement
124
replaceMap?: Record<string, string>;
125

126
// Sort filenames alphabetically
127
sort?: boolean;
128
```
129

130
**Usage Examples:**
131

132
```typescript
133
// Keep full paths (don't remove common prefix)
134
const result = await explore("bundle.js", {
135
  noRoot: true
136
});
137

138
// Replace path segments for cleaner display
139
const result = await explore("bundle.js", {
140
  replaceMap: {
141
    "node_modules": "deps",
142
    "src/components": "components"
143
  }
144
});
145

146
// Sort filenames for consistent output
147
const result = await explore("bundle.js", {
148
  sort: true
149
});
150

151
// Combined path processing
152
const result = await explore("bundle.js", {
153
  noRoot: false,
154
  sort: true,
155
  replaceMap: {
156
    "/very/long/project/path": "",
157
    "node_modules": "deps"
158
  }
159
});
160
```
161

162
### Validation Options
163

164
Control source map validation and error checking behavior.
165

166
```typescript { .api }
167
// Disable invalid mapping column/line checks
168
noBorderChecks?: boolean;
169
```
170

171
**Usage Examples:**
172

173
```typescript
174
// Disable strict mapping validation (for problematic source maps)
175
const result = await explore("bundle.js", {
176
  noBorderChecks: true
177
});
178

179
// Enable all validation (default behavior)
180
const result = await explore("bundle.js", {
181
  noBorderChecks: false
182
});
183
```
184

185
### Coverage Integration
186

187
Support for Chrome DevTools code coverage data to create heat map visualizations.
188

189
```typescript { .api }
190
// Path to Chrome code coverage JSON export
191
coverage?: string;
192
```
193

194
**Usage Examples:**
195

196
```typescript
197
// Add code coverage heat map
198
const result = await explore("bundle.js", {
199
  coverage: "coverage-data.json",
200
  output: { format: "html" }
201
});
202

203
// Coverage with other options
204
const result = await explore("bundle.js", {
205
  coverage: "./chrome-coverage.json",
206
  gzip: true,
207
  output: { format: "html", filename: "coverage-analysis.html" }
208
});
209
```
210

211
## Common Configuration Patterns
212

213
### Development Analysis
214

215
Typical settings for development-time bundle analysis:
216

217
```typescript
218
const devConfig: ExploreOptions = {
219
  output: { format: "html" },
220
  sort: true,
221
  replaceMap: {
222
    "node_modules": "deps",
223
    "src/": ""
224
  }
225
};
226

227
const result = await explore("dist/*.js", devConfig);
228
```
229

230
### CI/CD Integration
231

232
Configuration for automated testing and reporting:
233

234
```typescript
235
const ciConfig: ExploreOptions = {
236
  output: { format: "json", filename: "bundle-analysis.json" },
237
  onlyMapped: true,
238
  sort: true,
239
  gzip: true
240
};
241

242
const result = await explore("dist/bundle.js", ciConfig);
243
```
244

245
### Production Optimization
246

247
Settings for detailed production bundle analysis:
248

249
```typescript
250
const prodConfig: ExploreOptions = {
251
  output: { format: "html", filename: "production-analysis.html" },
252
  gzip: true,
253
  sort: true,
254
  coverage: "production-coverage.json",
255
  replaceMap: {
256
    "/app/build/": "",
257
    "node_modules": "dependencies"
258
  }
259
};
260

261
const result = await explore("build/static/js/*.js", prodConfig);
262
```
263

264
### Debug Analysis
265

266
Configuration for troubleshooting source map issues:
267

268
```typescript
269
const debugConfig: ExploreOptions = {
270
  output: { format: "json" },
271
  noBorderChecks: true,
272
  noRoot: true,
273
  onlyMapped: false,
274
  excludeSourceMapComment: false
275
};
276

277
const result = await explore("problematic-bundle.js", debugConfig);
278
```
279

280
## Option Interactions
281

282
### Automatic Option Adjustments
283

284
Some options automatically affect others:
285

286
- Setting `gzip: true` automatically sets `onlyMapped: true` (unmapped bytes can't be calculated with gzip)
287
- CLI equivalents exist for all programmatic options
288

289
### Conflicting Options
290

291
The library handles conflicting options gracefully:
292

293
- `gzip: true` overrides `onlyMapped: false`
294
- Output format conflicts are resolved by using the last specified format
295
- Invalid combinations are logged as warnings but don't prevent analysis