0
# Metro Symbolicate
1

2
Metro Symbolicate is a command-line tool and JavaScript library for symbolicating stack traces using source maps. It translates minified or bundled JavaScript errors back to their original source locations, making it essential for debugging React Native applications and other JavaScript bundles where source maps are available.
3

4
## Package Information
5

6
- **Package Name**: metro-symbolicate
7
- **Package Type**: npm
8
- **Language**: JavaScript (with Flow types)
9
- **Installation**: `npm install metro-symbolicate`
10

11
## Core Imports
12

13
For CLI usage:
14
```bash
15
npx metro-symbolicate <source-map-file>
16
```
17

18
For programmatic usage:
19
```javascript
20
const Symbolication = require('metro-symbolicate/private/Symbolication');
21
const SourceMetadataMapConsumer = require('metro-symbolicate/private/SourceMetadataMapConsumer');
22
const GoogleIgnoreListConsumer = require('metro-symbolicate/private/GoogleIgnoreListConsumer');
23
const { ChromeHeapSnapshotProcessor } = require('metro-symbolicate/private/ChromeHeapSnapshot');
24
```
25

26
Using main entry point:
27
```javascript
28
const symbolicateMain = require('metro-symbolicate');
29
```
30

31
## Basic Usage
32

33
### CLI Stack Trace Symbolication
34

35
Symbolicate a stack trace from stdin:
36
```bash
37
cat stacktrace.txt | npx metro-symbolicate bundle.js.map
38
```
39

40
Symbolicate specific coordinates:
41
```bash
42
npx metro-symbolicate bundle.js.map 42 15
43
```
44

45
### Programmatic Usage
46

47
```javascript
48
const Symbolication = require('metro-symbolicate/private/Symbolication');
49
const { SourceMapConsumer } = require('source-map');
50
const fs = require('fs');
51

52
// Create symbolication context
53
const sourceMapContent = fs.readFileSync('bundle.js.map', 'utf8');
54
const context = Symbolication.createContext(SourceMapConsumer, sourceMapContent);
55

56
// Symbolicate a stack trace
57
const stackTrace = `
58
Error: Something went wrong
59
    at Object.foo (bundle.js:1:234)
60
    at bar (bundle.js:2:456)
61
`;
62

63
const symbolicatedTrace = context.symbolicate(stackTrace);
64
console.log(symbolicatedTrace);
65

66
// Get original position for specific coordinates
67
const original = context.getOriginalPositionFor(1, 234);
68
console.log(original); // { source: 'src/foo.js', line: 10, column: 5, name: 'foo' }
69
```
70

71
## Architecture
72

73
Metro Symbolicate is built around several core components:
74

75
- **CLI Interface**: Command-line tool handling various input formats and options
76
- **Symbolication Engine**: Core logic for translating bundled positions to original source locations
77
- **Source Map Processing**: Integration with standard source-map library and Metro-specific extensions
78
- **Metadata Consumers**: Specialized processors for function names, ignore lists, and other source map metadata
79
- **Chrome Integration**: Support for Chrome DevTools formats including CPU profiles and heap snapshots
80

81
## Capabilities
82

83
### CLI Interface
84

85
Command-line tool supporting multiple input formats including stack traces, explicit coordinates, profiler maps, CPU profiles, and heap snapshots.
86

87
```bash { .api }
88
metro-symbolicate <source-map-file> [options]
89
metro-symbolicate <source-map-file> <line> [column]
90
metro-symbolicate <source-map-file> <moduleId>.js <line> [column]
91
metro-symbolicate <source-map-file> <file>.profmap
92
metro-symbolicate <source-map-file> <file>.cpuprofile
93
metro-symbolicate <source-map-file> <file>.heapsnapshot|.heaptimeline
94
metro-symbolicate <source-map-file> --attribution < in.jsonl > out.jsonl
95
```
96

97
[CLI Interface](./cli-interface.md)
98

99
### Core Symbolication
100

101
Core API for creating symbolication contexts and translating bundle positions to original source locations.
102

103
```javascript { .api }
104
function createContext(
105
  SourceMapConsumer: typeof SourceMapConsumer,
106
  sourceMapContent: string,
107
  options?: ContextOptionsInput
108
): SymbolicationContext;
109

110
function unstable_createDirectoryContext(
111
  SourceMapConsumer: typeof SourceMapConsumer,
112
  sourceMapDir: string,
113
  options?: ContextOptionsInput
114
): SymbolicationContext;
115
```
116

117
[Core Symbolication](./core-symbolication.md)
118

119
### Source Metadata Processing
120

121
Enhanced source map processing with support for function names and Facebook-specific metadata extensions.
122

123
```javascript { .api }
124
class SourceMetadataMapConsumer {
125
  constructor(map: MixedSourceMap, normalizeSourceFn?: SourceNameNormalizer);
126
  functionNameFor({line, column, source}: {line: number, column: number, source: ?string}): ?string;
127
  toArray(sources: Array<string>): Array<?{[number]: any}>;
128
}
129
```
130

131
[Source Metadata](./source-metadata.md)
132

133
### Google Ignore List Processing
134

135
Processing of Google's ignore list extension for source maps, used to mark generated or third-party code.
136

137
```javascript { .api }
138
class GoogleIgnoreListConsumer {
139
  constructor(map: MixedSourceMap, normalizeSourceFn?: SourceNameNormalizer);
140
  isIgnored({source}: {source: ?string}): boolean;
141
  toArray(sources: Array<?string>): Array<number>;
142
}
143
```
144

145
[Google Ignore List](./ignore-list.md)
146

147
### Chrome DevTools Integration
148

149
Support for symbolicating Chrome DevTools formats including CPU profiles and heap snapshots.
150

151
```javascript { .api }
152
class ChromeHeapSnapshotProcessor {
153
  constructor(snapshot: ChromeHeapSnapshot);
154
  symbolicateLocation(locationIdx: number, context: SymbolicationContext): void;
155
  expandLocations(context: SymbolicationContext): void;
156
}
157
```
158

159
[Chrome DevTools Integration](./chrome-devtools.md)
160

161
## Types
162

163
```javascript { .api }
164
type ContextOptionsInput = {
165
  nameSource?: 'function_names' | 'identifier_names';
166
  inputLineStart?: number;
167
  inputColumnStart?: number;
168
  outputLineStart?: number;
169
  outputColumnStart?: number;
170
};
171

172
type SingleMapModuleIds = {
173
  segmentId: number;
174
  localId: ?number;
175
};
176

177
type SourceNameNormalizer = (string, {sourceRoot?: ?string}) => string;
178

179
interface SymbolicationContext {
180
  symbolicate(stackTrace: string): string;
181
  getOriginalPositionFor(
182
    line: number,
183
    column: number,
184
    moduleIds?: ?SingleMapModuleIds
185
  ): ?{
186
    source: ?string;
187
    line: ?number;
188
    column: ?number;
189
    name: ?string;
190
  };
191
  parseFileName(fileName: string): ?SingleMapModuleIds;
192
  symbolicateProfilerMap(profMapFile: string): string;
193
  symbolicateAttribution(obj: Object): void;
194
  symbolicateChromeTrace(traceFile: string, streams: {stdout: any, stderr: any}): void;
195
  symbolicateHermesMinidumpTrace(crashInfo: HermesMinidumpCrashInfo): SymbolicatedStackTrace;
196
  symbolicateHermesCoverageTrace(coverageInfo: HermesCoverageInfo): SymbolicatedStackTrace;
197
  symbolicateHeapSnapshot(snapshotContent: string): ChromeHeapSnapshot;
198
}
199
```