denandz/sourcemapper: extracting JavaScript source trees from source maps

Sourcemapper input modes and JavaScript link resolution

The command accepts exactly one source selector: `-url`, `-jsurl`, or `-dir`. With `-url`, the selected resource can be an HTTP URL or a local path to a `.map` file. Sourcemapper downloads or opens that resource, parses it as JSON, and writes the represented sources under the required `-output` directory.

The `-jsurl` mode adds discovery. The program reads a JavaScript file and checks its body for a source map reference. According to the README, absolute, relative, and `data:` references are supported. Resolution is based on the Source Map specification rules linked by the project, including rules for relating generated code to a map. An inline base64 map can be handled directly through this mode.

For `-dir`, Sourcemapper recursively walks the selected directory and processes every `.map` file it finds. Bad or empty maps are logged and skipped so one invalid file does not stop the batch. This behavior makes the mode suitable for an archive of downloaded maps, although it does not recover maps that were never placed in the directory.

Network-oriented flags include `-header`, `-proxy`, and `-insecure`. Headers may be repeated in the curl-like form described by the help output. The presence of `-insecure` is a notable operational boundary: it tells the program to ignore invalid TLS certificates. That option can be useful in inspection environments with interception or internal certificate infrastructure, but it removes certificate validation and should be selected only when the target and connection path are understood.

Installing the Sourcemapper Go command

The README gives `go install` as the normal installation route when a recent Go version is available. This installs the module path at its latest published Go module version. The repository declares Go 1.16 in `go.mod`; the README does not state a tested matrix for newer Go releases.

Run this command to install it:

go install github.com/denandz/sourcemapper@latest

A user who needs the repository source can clone and build it instead:

git clone https://github.com/denandz/sourcemapper
cd sourcemapper
go get
go build

The second route leaves a local `sourcemapper` binary in the repository directory after `go build`. BlackArch Linux users have a separate package command documented by the README:

pacman -S sourcemapper

There are no GitHub releases, so there is no documented release archive or versioned binary procedure to choose among. The `go install ...@latest` path is versioned through Go modules, while the clone and build path follows the default `master` branch.

Extracting a local or remote .map file for a first use

Every invocation needs `-output`. For the first direct extraction, use a `.map` URL or a local `.map` path and select a new output directory. The following command is copied from the README:

./sourcemapper -output dhubsrc -url https://hub.docker.com/public/js/client.356c14916fb23f85707f.js.map

The README states that Dockerhub has since removed that map file. The command therefore documents the invocation shape, but it no longer provides the output shown in the original example. If a map is stored locally, the same `-url` option can receive its path.

The program then creates paths based on the source names recorded in the map. In the README example, those names include webpack-style paths such as `/app/scripts/client.js` and directories containing `~` and `:` characters. The output reflects source-map paths rather than a flat list of files.

Review `-output` before processing a map from an untrusted source. The project accepts the directory as the root for recreated source files, but the README does not document a flag for sanitizing or mapping absolute-looking source paths. A successful run ends with a completion message after writing extracted files. A missing resource, invalid JSON, or unsupported map content would instead indicate that the selected input is not usable for this operation.

Following inline source maps from JavaScript with -jsurl

Direct JavaScript processing is appropriate when the map is embedded through `sourceMappingURL` rather than downloaded separately. Use `-jsurl` with a JavaScript URL and an output directory:

./sourcemapper -output test -jsurl http://localhost:8080/main.js

The README's example shows the program retrieving `main.js`, finding a `data:application/json;charset=utf-8;base64,...` reference in its body, decoding the inline data, parsing it as a version 3 source map, and writing its sources. The same mode supports absolute and relative references, subject to the source-map linking rules cited by the project.

This path removes a manual preprocessing step, but it also means the command makes an additional request chain. A relative reference is resolved from the JavaScript resource, while an absolute reference points elsewhere. Headers and proxy settings can affect retrieval. If the server requires authorization, `-header` can be repeated with header values in the format documented by the help text.

The project also exposes `-proxy` for proxy configuration and `-insecure` for ignoring invalid TLS certificates. The README does not provide examples for those options, so their exact configuration should come from the server and network environment rather than an invented command line.

Batch directory processing and its failure boundary

For multiple map files, replace `-url` with `-dir`:

./sourcemapper -dir ./maps -output ./src

Sourcemapper recursively searches `./maps` for `.map` files, reports the number found, and processes each one into `./src`. The README states that invalid or empty maps are logged and skipped. That policy favors completion of the batch over stopping at the first bad input, but a successful final message should be paired with inspection of earlier log lines to determine whether every candidate map was usable.

Directory mode does not download arbitrary JavaScript files merely because they sit beside a map. It selects `.map` files found by the recursive walk. To process embedded or separately referenced maps in JavaScript, invoke `-jsurl` for the relevant JavaScript URL instead. Combining `-dir`, `-url`, and `-jsurl` is explicitly unsupported.

A second failure boundary concerns output collisions and path shape. The documented examples show that source names can produce nested directories and characters such as `:` and `~`. The README does not document collision handling, overwrite policy, sandboxing, or path normalization. For maps from different bundles that contain similar source names, inspect the logs and use separate `-output` roots when preserving provenance matters.

Sourcemapper maintenance, licensing, and manual alternatives

The repository is not archived, and its last push was on 2026-07-24. That is recent development activity at the repository level, but it is not proof of release cadence or long-term support. There are no GitHub releases. Consumers therefore have no documented stable-release channel in the repository, and `@latest` depends on Go module resolution.

The project uses the BSD 3-Clause license. Its `LICENSE` file should be reviewed for the actual obligations and notice text. At a technical level, adopting an individual BSD-licensed source map does not erase copyright in the JavaScript files contained in that map. The README does not claim that Sourcemapper grants rights to extracted application code, so users must determine those rights separately.

There is a real alternative for inline maps: decode the `data:` URL, save it as a `.map` file, then pass that file to `-url`. The README presents this as a way to handle base64 blobs outside direct JavaScript parsing. Compared with `-jsurl`, the manual route requires decoding the map yourself but avoids asking Sourcemapper to retrieve and inspect the JavaScript file. For deployments where the map is already downloaded, direct `-url` processing is simpler than obtaining the JavaScript bundle and scanning it for a reference.

Neither alternative turns the utility into a decompiler. Without an accessible source map and embedded source content, the tool has no documented input from which to recreate the original tree.

Editorial conclusion

Adopt Sourcemapper when you have a public source map, an inline map, or a directory of `.map` files and need their listed JavaScript sources written to disk. Do not choose it when the map is missing, damaged, or does not contain the source content you want. Verify first that the source map resolves, that only one of `-url`, `-jsurl`, or `-dir` is supplied, and that the `-output` directory is acceptable for the paths stored in the map. For the current `master` branch, the last push was on 2026-07-24, while the repository has no published GitHub releases.

Frequently asked questions

Official sources

1. denandz/sourcemapper on GitHub
2. Issues
3. License: BSD-3-Clause
4. README