sourcemap

sourcemap is a Rust crate that implements the JavaScript sourcemap format end to end: decoding regular sourcemaps, indexed sourcemaps, and React Native’s Hermes/Facebook variant, encoding new maps back to JSON, and looking up original source locations from generated line/column positions via a hand-rolled VLQ codec. It underpins Sentry’s own error-symbolication pipeline, where minified JavaScript stack traces are mapped back to original source files and function names.

Beyond straight decode/lookup, the crate supports rewriting sourcemaps (stripping names, dropping source contents, remapping source roots, resolving local source files onto disk), building new sourcemaps token-by-token via SourceMapBuilder, and an optional ram_bundle feature for React Native’s RAM/Hermes bundle format. It is intentionally scoped to the sourcemap format itself rather than any particular bundler or transpiler, making it usable from any Rust tool that needs to read, generate, or manipulate sourcemaps — source-map uploaders, minifiers, bundlers, or crash-reporting agents.

What You Get

• Sourcemap decoding - parse regular sourcemaps, sourcemap indexes, and data-URL-embedded maps from a reader or byte slice via SourceMap::from_reader / decode / decode_slice.
• Token lookup - lookup_token(line, col) resolves a generated position to its original source file, line, column, and (optionally) symbol name.
• Sourcemap building and encoding - SourceMapBuilder constructs new sourcemaps token-by-token; encode/to_writer serializes any decoded map variant back to the standard JSON format.
• Rewriting controls - RewriteOptions lets callers strip names, drop or inline source contents, remap source roots, and strip common path prefixes when re-emitting a sourcemap.
• Hermes/RAM bundle support - dedicated SourceMapHermes decoding for React Native’s Metro+Hermes sourcemap variant, plus an opt-in ram_bundle feature for parsing React Native RAM bundle indexes and module entries.
• Sourcemap reference detection - locate_sourcemap_reference finds the //# sourceMappingURL= comment in a generated JS file to locate its companion map.

Common Use Cases

• Error-tracking symbolication - crash-reporting backends (like Sentry) resolve minified JS stack frames back to original source locations and function names for readable error reports.
• Sourcemap upload/validation tooling - CLI tools that validate, strip debug info from, or re-package sourcemaps before uploading them to a symbol server.
• Custom JS/TS build tooling written in Rust - bundlers, minifiers, or transformers written in Rust that need to read an incoming sourcemap or emit an accurate one for their own output.
• React Native crash symbolication - resolving Hermes bytecode or RAM bundle offsets back to original JavaScript source for React Native crash reports.

Under The Hood

Architecture The crate is organized as a set of focused modules under src/: decoder.rs and encoder.rs handle the JSON<->typed-struct boundary (including a StripHeaderReader that strips the )]}' XSSI-protection header some sourcemaps prepend), types.rs defines the core SourceMap/SourceMapIndex/DecodedMap/Token data model and lookup logic, builder.rs provides an incremental SourceMapBuilder for constructing maps, vlq.rs implements the base64-VLQ segment codec the format’s mappings field is built on, and hermes.rs plus ram_bundle.rs layer React Native-specific formats (SourceMapHermes, RAM bundle indexes) on top of the same core types via composition rather than inheritance. lib.rs re-exports a small, curated public surface (SourceMap, SourceMapBuilder, decode/decode_slice, Token, DecodedMap) so downstream crates interact with a handful of well-documented entry points rather than the internal module structure directly. Tech Stack It’s a dependency-light Rust library: serde/serde_json for JSON (de)serialization, url for source URL handling, data-encoding and base64-simd for base64/VLQ decoding, debugid for React Native/Hermes debug identifiers, bitvec for compact bit-level parsing in the RAM bundle path, and rustc-hash for fast hashing in lookup tables. The optional ram_bundle feature pulls in scroll for binary struct parsing of RAM bundle files. There’s no async runtime, no I/O beyond std::io::Read/Write, and no unsafe code in the core library, keeping it embeddable in any Rust context including WASM or FFI-bound tooling. Code Quality The crate has a substantial tests/ directory with one file per module (test_decoder.rs, test_encoder.rs, test_builder.rs, test_hermes.rs, test_index.rs, test_namemap.rs, test_regular.rs, test_detector.rs) plus JSON/sourcemap fixtures, and dev-dependencies include proptest for property-based testing of the VLQ/encoding logic. Errors are modeled as a single typed Error enum (src/errors.rs) with explicit From conversions from io::Error, serde_json::Error, UTF-8 errors, and format-specific variants like BadSegmentSize/BadSourceReference/InvalidRamBundleMagic rather than panics or string errors. CI runs cargo fmt --check, cargo clippy -D clippy::all across the whole workspace, cargo test --workspace in both default and all-features configurations, and a docs build with RUSTDOCFLAGS=-Dwarnings, so lint, type, and doc-comment regressions are all caught pre-merge. What Makes It Unique Most sourcemap tooling lives in the JavaScript ecosystem (source-map, magic-string); this crate is one of the few complete, actively-used implementations written natively in Rust, letting Rust-based build tools, crash reporters, and symbolication services avoid shelling out to Node or embedding a JS runtime just to read a sourcemap. Its Hermes/RAM bundle support is comparatively rare — most general-purpose sourcemap libraries don’t handle React Native’s Metro+Hermes variant at all — and reflects its origin inside Sentry’s own mobile crash-symbolication pipeline, where it needs to resolve both regular JS and Hermes-bytecode stack frames using the same API surface.