source-map-explorer

source-map-explorer analyzes the source maps your bundler already generates to show precisely which original source files are responsible for each byte of your minified JavaScript (or Sass/LESS) output. Instead of guessing from module-graph heuristics, it walks the actual source-map mappings to attribute compiled bytes back to real files, then renders the result as an interactive treemap, or as JSON/TSV for scripting.

It ships as both a CLI (source-map-explorer / sme) and a small Node API (explore()), so it fits equally well into a one-off terminal investigation or an automated CI check that flags bundle-size regressions. Optional gzip-size calculation and Chrome DevTools coverage overlays let teams see not just what’s in the bundle, but what actually ships over the wire and what code actually runs.

What You Get

• An interactive, zoomable HTML treemap showing exactly how many bytes each source file contributes to your bundle
• JSON/TSV export options for piping results into other tooling or dashboards
• A CLI (source-map-explorer / sme) and an equivalent async explore() JS API for scripted/CI use
• Gzip-size calculation and Chrome-coverage overlay support for deeper, production-realistic analysis

Common Use Cases

• Investigating why a webpack/Rollup/esbuild bundle is larger than expected
• Spotting accidental duplicate package versions bundled together
• Auditing third-party dependency weight before shipping to production
• Tracking bundle-size regressions in CI over time

Under The Hood

Architecture The codebase is organized as small focused modules under src/lib (explore.ts, api.ts, helpers.ts, coverage.ts, output.ts, html.ts, app-error.ts) plus a thin CLI wrapper (src/cli/cli.ts) that parses yargs options and delegates entirely to the library’s explore() function, giving a clean separation between the public library and the command-line entry point. Data flows in one direction: source files or glob tokens are resolved into Bundle objects in api.ts, each bundle is analyzed in explore.ts by walking source-map mappings via the source-map package’s consumer to attribute minified byte ranges back to original source files, coverage data is merged in via coverage.ts when supplied, and results are handed to output.ts/html.ts for JSON/TSV/HTML/treemap rendering. Errors are centralized through a single typed AppError class with an error-code enum, keeping the mapping/parsing pipeline’s failure modes consistent. The core abstraction is exploreBundle(); if its return shape changed, both the CLI formatter and the public API surface would need to move in lockstep, since both re-export the same functions.

Tech Stack Written in TypeScript targeting ES2018/CommonJS, compiled via tsc with a small build pipeline (npm-run-all plus copyfiles to move vendored assets and an EJS template from src to lib). CLI parsing runs through yargs in strict mode; source-map parsing depends on Mozilla’s source-map package for WASM-backed mapping lookups and convert-source-map for extracting inline or file-referenced source-map comments, with gzip-size for optional gzip-based sizing. Output rendering combines ejs templates with a bundled webtreemap vendor script and stylesheet for the interactive treemap, chalk for colored terminal output, open to launch the HTML report in a browser, and temp for scratch files, with general utility needs covered by lodash. The test stack layers Mocha, Chai, and chai-as-promised on top of ts-node, with nyc/Istanbul coverage reported to Coveralls.

Code Quality Unit, end-to-end, and performance suites live under tests/unit, tests/e2e, and tests/performance respectively, each with its own Mocha config, orchestrated via npm-run-all, with snapshot testing through @smpx/snap-shot-it. Error handling is explicit and typed through the AppError class rather than raw throws. A husky pre-commit hook runs the full test suite plus lint-staged (ESLint with typescript-eslint, Prettier) before every commit, and naming conventions are consistent across the codebase, with strict TypeScript compiler options enabled. Recent commit activity is limited, though the existing test/lint infrastructure is comprehensive.

API Design The public API centers on a single, well-documented explore(bundlesAndFileTokens, options) async function that accepts a glob string, an explicit filename, an in-memory {code, map} bundle object, or an array mixing all three, letting bundler integrations plug it in without touching the filesystem contract the CLI uses. Options are a flat, typed object (onlyMapped, excludeSourceMapComment, noRoot, replaceMap, coverage, gzip) documented in the README with concrete examples for every output format, and the CLI mirrors the same option names, so there’s no relearning between programmatic and command-line use. Getting started takes a single import and one function call, and the returned result shape (bundles, errors, output) stays consistent across success and partial-failure cases. This is a well-executed but conventional wrapper around an existing source-map consumer rather than a novel abstraction.