tessl/npm-metro-symbolicate

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

CLI Interface

Name: tessl/npm-metro-symbolicate
Author: tessl

Command-line interface for metro-symbolicate supporting multiple input formats and symbolication options.

Capabilities

Stack Trace Symbolication from Stdin

Reads stack traces from standard input and symbolicates them using the provided source map.

metro-symbolicate <source-map-file>

Usage Examples:

# Symbolicate stack trace from file
cat error-stack-trace.txt | metro-symbolicate bundle.js.map

# Symbolicate stack trace piped from another command
node app.js 2>&1 | metro-symbolicate bundle.js.map

# With function name options
cat stack.txt | metro-symbolicate bundle.js.map --no-function-names

Explicit Coordinate Symbolication

Symbolicates specific line and column coordinates in the bundled code.

metro-symbolicate <source-map-file> <line> [column]

Parameters:

line - Line number in the bundled code (1-based by default)
column - Column number in the bundled code (0-based by default, optional)

Usage Examples:

# Symbolicate line 42, column 15
metro-symbolicate bundle.js.map 42 15

# Symbolicate line 100, column defaults to 0
metro-symbolicate bundle.js.map 100

# With custom line/column start offsets
metro-symbolicate bundle.js.map 42 15 --input-line-start 0 --input-column-start 1

Module ID Symbolication

Symbolicates coordinates within a specific module in segmented bundles (e.g., RAM bundles).

metro-symbolicate <source-map-file> <moduleId>.js <line> [column]

Parameters:

moduleId - Module identifier followed by .js
line - Line number within the module
column - Column number within the module (optional)

Usage Examples:

# Symbolicate line 10 in module 123
metro-symbolicate bundle.js.map 123.js 10

# Symbolicate line 10, column 5 in module 456
metro-symbolicate bundle.js.map 456.js 10 5

Profiler Map Symbolication

Symbolicates React Native profiler maps (.profmap files).

metro-symbolicate <source-map-file> <file>.profmap

Usage Examples:

# Symbolicate profiler map
metro-symbolicate bundle.js.map trace.profmap > symbolicated-trace.profmap

# Process profiler data from React Native
metro-symbolicate index.android.bundle.map profile-12345.profmap

CPU Profile Symbolication

Symbolicates Chrome DevTools CPU profiles (.cpuprofile files).

metro-symbolicate <source-map-file> <file>.cpuprofile

Usage Examples:

# Symbolicate CPU profile
metro-symbolicate bundle.js.map cpu-profile.cpuprofile

# Process Chrome DevTools performance data
metro-symbolicate app.js.map performance-profile.cpuprofile

Heap Snapshot Symbolication

Symbolicates Chrome DevTools heap snapshots and heap timelines.

metro-symbolicate <source-map-file> <file>.heapsnapshot
metro-symbolicate <source-map-file> <file>.heaptimeline

Usage Examples:

# Symbolicate heap snapshot
metro-symbolicate bundle.js.map heap-snapshot.heapsnapshot > symbolicated.json

# Symbolicate heap timeline
metro-symbolicate bundle.js.map allocation-timeline.heaptimeline > timeline.json

Attribution File Processing

Processes JSONL attribution files for bundle size analysis.

metro-symbolicate <source-map-file> --attribution < input.jsonl > output.jsonl

Usage Examples:

# Process bundle attribution data
metro-symbolicate bundle.js.map --attribution < bundle-sizes.jsonl > attributed-sizes.jsonl

# Chain with bundle analysis tools
analyze-bundle bundle.js | metro-symbolicate bundle.js.map --attribution > results.jsonl

Hermes Integration

Special modes for processing Hermes JavaScript engine crash dumps and coverage traces.

metro-symbolicate <source-map-file> --hermes-crash
metro-symbolicate <source-map-file> --hermes-coverage

Hermes Crash Mode: Processes Hermes crash dump JSON from stdin and outputs symbolicated stack traces.

cat hermes-crash.json | metro-symbolicate bundle.js.map --hermes-crash

Hermes Coverage Mode: Processes Hermes coverage trace JSON from stdin for code coverage analysis.

cat coverage-trace.json | metro-symbolicate bundle.js.map --hermes-coverage

CLI Options

Function Name Options

--no-function-names

Use identifier names instead of function names in symbolicated output. By default, metro-symbolicate attempts to use function names from source map metadata.

Hermes Options

--hermes-crash
--hermes-coverage

Special processing modes for Hermes JavaScript engine. These options are mutually exclusive.

--hermes-crash: Process Hermes minidump crash information
--hermes-coverage: Process Hermes code coverage traces

Line and Column Offset Options

Control how line and column numbers are interpreted and displayed.

--input-line-start <number>     # Default: 1
--input-column-start <number>   # Default: 0
--output-line-start <number>    # Default: 1
--output-column-start <number>  # Default: 0

Usage Examples:

# 0-based input, 1-based output (common for some tools)
metro-symbolicate bundle.js.map 0 5 --input-line-start 0 --output-line-start 1

# All 1-based numbering
metro-symbolicate bundle.js.map 1 6 --input-line-start 1 --input-column-start 1

Directory-based Source Maps

Metro-symbolicate can work with directories containing multiple source map files instead of a single source map file.

metro-symbolicate <source-map-directory>/

Usage Examples:

# Use directory of source maps
metro-symbolicate ./source-maps/ 42 15

# Process stack trace with directory
cat stack.txt | metro-symbolicate ./maps/

Error Handling

The CLI returns appropriate exit codes:

0: Success
1: Error (invalid arguments, file not found, parsing errors, etc.)

Common error scenarios:

Invalid source map file or directory
Malformed stack traces or input data
Conflicting command-line options (e.g., --hermes-crash with --hermes-coverage)
Missing required arguments