0
# Metro Source Map
1

2
Metro Source Map is a comprehensive source map generation and consumption library designed for the Metro JavaScript bundler used in React Native development. It provides advanced source mapping capabilities including source map composition, bundle building with index maps, source map consumption and generation, function map generation for debugging support, and various encoding utilities for efficient source map storage.
3

4
## Package Information
5

6
- **Package Name**: metro-source-map
7
- **Package Type**: npm
8
- **Language**: JavaScript (Flow-typed)
9
- **Installation**: `npm install metro-source-map`
10

11
## Core Imports
12

13
```javascript
14
const {
15
  BundleBuilder,
16
  Consumer,
17
  composeSourceMaps,
18
  fromRawMappings,
19
  fromRawMappingsNonBlocking,
20
  generateFunctionMap,
21
  functionMapBabelPlugin,
22
  createIndexMap,
23
  normalizeSourcePath,
24
  toBabelSegments,
25
  toSegmentTuple
26
} = require("metro-source-map");
27
```
28

29
Note: This package uses CommonJS exports only. ES6 import syntax is not supported.
30

31
## Basic Usage
32

33
```javascript
34
const { fromRawMappings, Consumer, BundleBuilder } = require("metro-source-map");
35

36
// Generate a source map from raw mappings
37
const modules = [
38
  {
39
    map: [[1, 0, 1, 0], [2, 0, 2, 0]], // [genLine, genCol, srcLine, srcCol]
40
    functionMap: null,
41
    path: "module1.js",
42
    source: "console.log('hello');",
43
    code: "console.log('hello');",
44
    isIgnored: false
45
  }
46
];
47

48
const generator = fromRawMappings(modules);
49
const sourceMap = generator.toMap("bundle.js");
50

51
// Consume a source map
52
const consumer = new Consumer(sourceMap);
53
const originalPosition = consumer.originalPositionFor({
54
  line: 1,
55
  column: 0
56
});
57

58
// Build a bundle with source maps
59
const builder = new BundleBuilder("output.js");
60
builder.append("console.log('hello');", someSourceMap);
61
const bundledCode = builder.getCode();
62
const bundledMap = builder.getMap();
63
```
64

65
## Architecture
66

67
Metro Source Map is built around several key components:
68

69
- **Generator System**: `Generator` class for creating source maps from raw mappings with support for Facebook extensions
70
- **Consumer System**: `Consumer` and related classes for reading and querying existing source maps
71
- **Bundle Builder**: `BundleBuilder` for concatenating code with proper source map composition
72
- **Composition Engine**: Utilities for combining multiple source maps into composite maps
73
- **Function Maps**: Facebook-specific debugging extensions for Hermes and React Native
74
- **Encoding Utilities**: Base64 VLQ encoding/decoding for efficient source map storage
75

76
## Capabilities
77

78
### Source Map Generation
79

80
Create source maps from raw mappings with support for Metro's specific requirements and Facebook extensions.
81

82
```javascript { .api }
83
function fromRawMappings(
84
  modules: Array<{
85
    map: ?Array<MetroSourceMapSegmentTuple>,
86
    functionMap: ?FBSourceFunctionMap,
87
    path: string,
88
    source: string,
89
    code: string,
90
    isIgnored: boolean,
91
    lineCount?: number
92
  }>,
93
  offsetLines?: number = 0
94
): Generator;
95

96
function fromRawMappingsNonBlocking(
97
  modules: Array<{
98
    map: ?Array<MetroSourceMapSegmentTuple>,
99
    functionMap: ?FBSourceFunctionMap,
100
    path: string,
101
    source: string,
102
    code: string,
103
    isIgnored: boolean,
104
    lineCount?: number
105
  }>,
106
  offsetLines?: number = 0
107
): Promise<Generator>;
108

109
// Generator class returned by fromRawMappings functions
110
class Generator {
111
  startFile(file: string, code: string, functionMap?: FBSourceFunctionMap, flags?: FileFlags): void;
112
  endFile(): void;
113
  addSimpleMapping(generatedLine: number, generatedColumn: number): void;
114
  addSourceMapping(generatedLine: number, generatedColumn: number, sourceLine: number, sourceColumn: number): void;
115
  addNamedSourceMapping(generatedLine: number, generatedColumn: number, sourceLine: number, sourceColumn: number, name: string): void;
116
  toMap(file?: string, options?: {excludeSource?: boolean}): BasicSourceMap;
117
  toString(file?: string, options?: {excludeSource?: boolean}): string;
118
}
119
```
120

121
[Source Map Generation](./generation.md)
122

123
### Source Map Consumption
124

125
Read and query source maps with support for both basic and indexed source map formats.
126

127
```javascript { .api }
128
class Consumer {
129
  static GENERATED_ORDER: IterationOrder;
130
  static ORIGINAL_ORDER: IterationOrder;
131
  static GREATEST_LOWER_BOUND: LookupBias;
132
  static LEAST_UPPER_BOUND: LookupBias;
133
  
134
  constructor(sourceMap: MixedSourceMap);
135
  originalPositionFor(generatedPosition: GeneratedPositionLookup): SourcePosition;
136
  generatedMappings(): Iterable<Mapping>;
137
  eachMapping(callback: (mapping: Mapping) => mixed, context?: mixed, order?: IterationOrder): void;
138
  get file(): ?string;
139
  sourceContentFor(source: string, nullOnMissing: true): ?string;
140
}
141

142
interface SourcePosition {
143
  source: ?string;
144
  line: ?number;
145
  column: ?number;
146
  name: ?string;
147
}
148

149
interface GeneratedPositionLookup {
150
  line: number;
151
  column: number;
152
  bias?: LookupBias;
153
}
154
```
155

156
[Source Map Consumption](./consumption.md)
157

158
### Bundle Building
159

160
Build source-mapped bundles by concatenating strings and their corresponding source maps.
161

162
```javascript { .api }
163
class BundleBuilder {
164
  constructor(file: string);
165
  append(code: string, map?: MixedSourceMap): this;
166
  getCode(): string;
167
  getMap(): MixedSourceMap;
168
}
169

170
function createIndexMap(file: string, sections: Array<IndexMapSection>): IndexMap;
171
```
172

173
[Bundle Building](./bundle-building.md)
174

175
### Source Map Composition
176

177
Compose multiple source maps into a single source map, useful for multi-stage transformations.
178

179
```javascript { .api }
180
function composeSourceMaps(maps: Array<MixedSourceMap>): MixedSourceMap;
181
```
182

183
[Source Map Composition](./composition.md)
184

185
### Function Map Generation
186

187
Generate Facebook-specific function maps for enhanced debugging support in Hermes and React Native.
188

189
```javascript { .api }
190
function generateFunctionMap(ast: BabelNode, context?: Context): FBSourceFunctionMap;
191
function functionMapBabelPlugin(): PluginObj;
192

193
interface FBSourceFunctionMap {
194
  names: Array<string>;
195
  mappings: string;
196
}
197

198
interface Context {
199
  filename?: ?string;
200
}
201
```
202

203
[Function Maps](./function-maps.md)
204

205
### Utility Functions
206

207
Additional utilities for source map manipulation and conversion.
208

209
```javascript { .api }
210
function toBabelSegments(sourceMap: BasicSourceMap): Array<BabelSourceMapSegment>;
211
function toSegmentTuple(mapping: BabelSourceMapSegment): MetroSourceMapSegmentTuple;
212
function normalizeSourcePath(source: string, sourceRoot?: ?string): string;
213
```
214

215
[Utilities](./utilities.md)
216

217
## Types
218

219
```javascript { .api }
220
type MetroSourceMapSegmentTuple =
221
  | [number, number]                           // GeneratedCodeMapping
222
  | [number, number, number, number]           // SourceMapping  
223
  | [number, number, number, number, string];  // SourceMappingWithName
224

225
interface BasicSourceMap {
226
  file?: string;
227
  mappings: string;
228
  names: Array<string>;
229
  sourceRoot?: string;
230
  sources: Array<string>;
231
  sourcesContent?: Array<?string>;
232
  version: number;
233
  x_facebook_offsets?: Array<number>;
234
  x_metro_module_paths?: Array<string>;
235
  x_facebook_sources?: FBSourcesArray;
236
  x_facebook_segments?: FBSegmentMap;
237
  x_hermes_function_offsets?: HermesFunctionOffsets;
238
  x_google_ignoreList?: Array<number>;
239
}
240

241
interface IndexMapSection {
242
  map: IndexMap | BasicSourceMap;
243
  offset: {
244
    line: number;
245
    column: number;
246
  };
247
}
248

249
interface IndexMap {
250
  file?: string;
251
  mappings?: void;
252
  sourcesContent?: void;
253
  sections: Array<IndexMapSection>;
254
  version: number;
255
  x_facebook_offsets?: Array<number>;
256
  x_metro_module_paths?: Array<string>;
257
  x_facebook_sources?: void;
258
  x_facebook_segments?: FBSegmentMap;
259
  x_hermes_function_offsets?: HermesFunctionOffsets;
260
  x_google_ignoreList?: void;
261
}
262

263
type MixedSourceMap = IndexMap | BasicSourceMap;
264

265
interface HermesFunctionOffsets {
266
  [number]: Array<number>;
267
}
268

269
type FBSourcesArray = Array<?FBSourceMetadata>;
270
type FBSourceMetadata = [?FBSourceFunctionMap];
271

272
interface FBSegmentMap {
273
  [id: string]: MixedSourceMap;
274
}
275

276
interface FileFlags {
277
  addToIgnoreList?: boolean;
278
}
279

280
// Additional types for external dependencies
281
type BabelNode = any; // From @babel/types
282
type PluginObj = any; // From Babel plugin system
283
type BabelSourceMapSegment = any; // From @babel/generator
284
type IterationOrder = number;
285
type LookupBias = number;
286
type Mapping = any;
287
```