or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

chrome-devtools.mdcli-interface.mdcore-symbolication.mdignore-list.mdindex.mdsource-metadata.md
tile.json

tessl/npm-metro-symbolicate

A tool to find the source location from JS bundles and stack traces.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/metro-symbolicate@0.83.x

To install, run

npx @tessl/cli install tessl/npm-metro-symbolicate@0.83.0

index.mddocs/

Metro Symbolicate

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.

Package Information

  • Package Name: metro-symbolicate
  • Package Type: npm
  • Language: JavaScript (with Flow types)
  • Installation: npm install metro-symbolicate

Core Imports

For CLI usage:

npx metro-symbolicate <source-map-file>

For programmatic usage:

const Symbolication = require('metro-symbolicate/private/Symbolication');
const SourceMetadataMapConsumer = require('metro-symbolicate/private/SourceMetadataMapConsumer');
const GoogleIgnoreListConsumer = require('metro-symbolicate/private/GoogleIgnoreListConsumer');
const { ChromeHeapSnapshotProcessor } = require('metro-symbolicate/private/ChromeHeapSnapshot');

Using main entry point:

const symbolicateMain = require('metro-symbolicate');

Basic Usage

CLI Stack Trace Symbolication

Symbolicate a stack trace from stdin:

cat stacktrace.txt | npx metro-symbolicate bundle.js.map

Symbolicate specific coordinates:

npx metro-symbolicate bundle.js.map 42 15

Programmatic Usage

const Symbolication = require('metro-symbolicate/private/Symbolication');
const { SourceMapConsumer } = require('source-map');
const fs = require('fs');

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

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

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

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

Architecture

Metro Symbolicate is built around several core components:

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

Capabilities

CLI Interface

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

metro-symbolicate <source-map-file> [options]
metro-symbolicate <source-map-file> <line> [column]
metro-symbolicate <source-map-file> <moduleId>.js <line> [column]
metro-symbolicate <source-map-file> <file>.profmap
metro-symbolicate <source-map-file> <file>.cpuprofile
metro-symbolicate <source-map-file> <file>.heapsnapshot|.heaptimeline
metro-symbolicate <source-map-file> --attribution < in.jsonl > out.jsonl

CLI Interface

Core Symbolication

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

function createContext(
  SourceMapConsumer: typeof SourceMapConsumer,
  sourceMapContent: string,
  options?: ContextOptionsInput
): SymbolicationContext;

function unstable_createDirectoryContext(
  SourceMapConsumer: typeof SourceMapConsumer,
  sourceMapDir: string,
  options?: ContextOptionsInput
): SymbolicationContext;

Core Symbolication

Source Metadata Processing

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

class SourceMetadataMapConsumer {
  constructor(map: MixedSourceMap, normalizeSourceFn?: SourceNameNormalizer);
  functionNameFor({line, column, source}: {line: number, column: number, source: ?string}): ?string;
  toArray(sources: Array<string>): Array<?{[number]: any}>;
}

Source Metadata

Google Ignore List Processing

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

class GoogleIgnoreListConsumer {
  constructor(map: MixedSourceMap, normalizeSourceFn?: SourceNameNormalizer);
  isIgnored({source}: {source: ?string}): boolean;
  toArray(sources: Array<?string>): Array<number>;
}

Google Ignore List

Chrome DevTools Integration

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

class ChromeHeapSnapshotProcessor {
  constructor(snapshot: ChromeHeapSnapshot);
  symbolicateLocation(locationIdx: number, context: SymbolicationContext): void;
  expandLocations(context: SymbolicationContext): void;
}

Chrome DevTools Integration

Types

type ContextOptionsInput = {
  nameSource?: 'function_names' | 'identifier_names';
  inputLineStart?: number;
  inputColumnStart?: number;
  outputLineStart?: number;
  outputColumnStart?: number;
};

type SingleMapModuleIds = {
  segmentId: number;
  localId: ?number;
};

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

interface SymbolicationContext {
  symbolicate(stackTrace: string): string;
  getOriginalPositionFor(
    line: number,
    column: number,
    moduleIds?: ?SingleMapModuleIds
  ): ?{
    source: ?string;
    line: ?number;
    column: ?number;
    name: ?string;
  };
  parseFileName(fileName: string): ?SingleMapModuleIds;
  symbolicateProfilerMap(profMapFile: string): string;
  symbolicateAttribution(obj: Object): void;
  symbolicateChromeTrace(traceFile: string, streams: {stdout: any, stderr: any}): void;
  symbolicateHermesMinidumpTrace(crashInfo: HermesMinidumpCrashInfo): SymbolicatedStackTrace;
  symbolicateHermesCoverageTrace(coverageInfo: HermesCoverageInfo): SymbolicatedStackTrace;
  symbolicateHeapSnapshot(snapshotContent: string): ChromeHeapSnapshot;
}