# mozilla/source-map: generating and consuming source maps in JavaScript

> The Mozilla source-map library is the reference JavaScript implementation of the source map format, split into a consumer, a generator and a SourceNode tree API. It is a low-level building block for tooling, not an end-user debugging product.

**mozilla/source-map** — Consume and generate source maps.

- Repository: https://github.com/mozilla/source-map
- Stars: 3,724 · Forks: 373
- Language: JavaScript
- License: NOASSERTION
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/mozilla-source-map

## What mozilla/source-map actually does for a build tool

A source map is a side file that records where each piece of generated code came from in the original source. The README describes this project as "a library to generate and consume the source map format", and that is the whole scope. It does not minify, transpile or bundle anything. It reads and writes the mapping data that those tools produce.

The audience is therefore narrow and technical: authors of compilers and bundlers that need to emit a map alongside their output, and authors of debuggers, error reporters and stack-trace mappers that need to turn a generated line and column back into a file, line, column and identifier name. If you are an application developer who just wants readable stack traces, this is one layer below what you want.

The split between the two roles shows up in the API surface. SourceMapConsumer handles the reading side with originalPositionFor and generatedPositionFor. SourceMapGenerator and SourceNode handle the writing side. The same package serves both, which is why it appears as a dependency in build pipelines rather than as a standalone tool.

## Inside the consumer: mappings, WASM and the initialize step

The interesting architectural detail is that the mapping parser is not plain JavaScript. The repository contains a wasm-mappings/ directory, and the README's browser example calls sourceMap.SourceMapConsumer.initialize with a "lib/mappings.wasm" key before any consumer is constructed. That means the consumer has an out-of-band dependency on a binary asset, and a bundler that ignores .wasm files will produce a build that fails at runtime rather than at compile time.

The consumer is asynchronous. The README's example wraps everything in await SourceMapConsumer.with(rawSourceMap, null, consumer => { ... }), and the API list also includes a constructor, new SourceMapConsumer(rawSourceMap), plus a prototype destroy() method. The presence of destroy() is a real constraint: consumers hold resources that are meant to be released, so long-lived processes that create consumers per request need to close them. The README does not spell out what happens if you skip destroy().

Lookups are positional. originalPositionFor takes a generated line and column and returns the source, line, column and name; generatedPositionFor goes the other way; allGeneratedPositionsFor returns every generated position that maps to one original position, which matters when a single source expression was inlined in several places. computeColumnSpans() exists to fill in column ranges for mappings that do not carry them. hasContentsOfAllSources() and sourceContentFor(source[, returnNullOnMissing]) tell you whether the map embedded the original text, and the second argument lets you choose between an exception and null for a missing source. That optional flag is the kind of detail that only matters when you are writing a tool that must not crash on a partial map.

## Generating a map with SourceNode and SourceMapGenerator

The writing side has two levels. SourceMapGenerator is the low level API: you call addMapping with a generated position, a source path, an original position and an optional name, then call toString(). The README's example produces the string '{"version":3,"file":"source-mapped.js","sources":["foo.js"],"names":["christopher"],"mappings":";;;;;;;;;mCAgCEA"}'. Note the leading semicolons: mappings are grouped per generated line and lines with no mappings are empty. That encoding is why hand-editing a mappings string is a bad idea.

SourceNode is the high level API and the one most compiler authors should reach for. You build a tree whose leaves carry a line, column, source and chunk of text, then call toStringWithSourceMap. The README's compile() example returns SourceNode instances for AST nodes and stringifies the result to get { code, map }. The advantage over addMapping is that positions are derived from the tree structure instead of being tracked by hand, which removes a whole class of off-by-one bugs.

Two more pieces round out the generator. setSourceContent embeds the original text into the map, which is what makes hasContentsOfAllSources() return true on the consumer side. applySourceMap composes maps, taking an existing consumer and rewriting this generator's mappings through it. Composition is the part most people underestimate: a two-stage build (TypeScript to JavaScript, then JavaScript through a bundler) produces two maps, and only composition gives you a map that points at the original TypeScript.

## Installing mozilla/source-map and mapping a position

The README gives a single install line for Node. Run it in your project directory:

```bash
npm install source-map
```

After that, the README's consuming example is the shortest path to a working lookup. The raw map below is copied from the README, including the sourceRoot, so the resolved source paths are absolute URLs:

```js
const rawSourceMap = {
  version: 3,
  file: "min.js",
  names: ["bar", "baz", "n"],
  sources: ["one.js", "two.js"],
  sourceRoot: "http://example.com/www/js/",
  mappings:
    "CAAC,IAAI,IAAM,SAAUA,GAClB,OAAOC,IAAID;CCDb,IAAI,IAAM,SAAUE,GAClB,OAAOA",
};
```

Pass that object to SourceMapConsumer.with along with a null source map URL, then query a generated position. The README's expected output for line 2, column 28 is the source http://example.com/www/js/two.js at line 2, column 10, with the name 'n':

```js
const whatever = await SourceMapConsumer.with(rawSourceMap, null, consumer => {
  console.log(
    consumer.originalPositionFor({
      line: 2,
      column: 28,
    })
  );
  return computeWhatever();
});
```

If you are loading the library in a browser instead of Node, the README uses a script tag from unpkg and then calls initialize with the WASM path before constructing a consumer:

```html
<script src="https://unpkg.com/source-map@0.7.3/dist/source-map.js"></script>
<script>
  sourceMap.SourceMapConsumer.initialize({
    "lib/mappings.wasm": "https://unpkg.com/source-map@0.7.3/lib/mappings.wasm",
  });
</script>
```

Two things to watch in that snippet. The version pinned in the URL is 0.7.3 while the recent releases listed for the repository are 0.7.5 and 0.7.6, so the README's example is behind the published versions. And the initialize call is mandatory on the web: skip it and the consumer has no parser to use.

## Where mozilla/source-map is the wrong choice

The first limitation is the WASM dependency. A consumer needs lib/mappings.wasm to be reachable, either from the filesystem in Node or from a URL in the browser. Any environment that cannot load a .wasm file, or any packaging step that drops it, breaks the library with no fallback path documented in the README.

The second is the version split. The README documents the 0.7.x API, and the two most recent releases are 0.7.5 and 0.7.6. But package.json on the default branch declares "version": "0.8.0". Whatever 0.8.0 contains is not described by the README, and the README's own browser example still pins 0.7.3. Anyone who installs from the repository rather than from the registry is working against documentation that does not match the code.

The third is scope. This library maps positions. It does not fetch a map for you, does not parse a //# sourceMappingURL comment out of a file, and does not print a human-readable stack trace. The related search phrase "source map failed to load" is a browser-devtools problem, not something this package diagnoses. If your goal is to inspect a bundle's composition, you want a visualizer or an explorer tool; this library is what such a tool would be built on, not the tool itself. And if you only need the browser to resolve maps during development, you need none of this: you need your bundler to emit the map.

## How it compares with the source-map-support approach

The nearest practical alternative for Node users is the source-map-support package, which is a consumer of this format rather than a competing implementation. The difference is one of layer. mozilla/source-map hands you a consumer object and expects you to call originalPositionFor yourself; source-map-support patches stack traces so that Error.prototype.stack already contains original file names and line numbers. One is a toolkit, the other is a runtime hook.

That distinction decides the choice. If you are writing a tool that needs to answer arbitrary mapping queries, compose two maps, or emit a map of its own, source-map-support cannot help you and mozilla/source-map is the right layer. If you are running a Node service and want readable traces in your logs, installing a library and calling a lookup function by hand is more work than you need. Bundlers sit in the same relationship: they depend on this format and typically ship their own copy of a consumer, which is why the phrase "source map webpack" appears in search data about this project even though this project is not webpack.

## Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-09. The two most recent releases, 0.7.5 and 0.7.6, are both dated 2025-07-24, so the published line has been stable for over a year while the branch has moved past it. That pattern, a documented stable API plus an undocumented 0.8.0 in package.json, is the main upgrade risk: pinning to a 0.7.x release keeps you on the documented surface, while tracking the branch means reading the CHANGELOG and the test suite to find out what changed.

The licence field is reported as NOASSERTION, which means the repository's licence could not be matched to a standard identifier automatically. The repository does contain a LICENSE file, so the terms are stated there rather than in the metadata. Read that file before shipping the library in a distributed product; this is a factual pointer, not legal advice.

Ongoing cost is low if you use the documented API. The API list in the README is small: a handful of consumer methods, four generator methods, and the SourceNode tree operations. The parts that need care are the WASM asset in your build pipeline and the destroy() call in long-running processes. Neither is documented in depth.

## Conclusion

Adopt mozilla/source-map if you are writing a bundler, transform, stack-trace mapper or debugger and need direct access to mappings, names and source contents. Do not adopt it if you want a finished CLI that explains a bundle: the README ships no command-line tool, and the repository's bench/ directory is not a user-facing analyzer. Before depending on it, verify which version npm resolves for you, because the README documents the 0.7.x API and asynchronous consumer while package.json on master declares version 0.8.0, and check whether your bundler already bundles its own copy of this library.

## FAQ

### How do I install mozilla/source-map in a Node project?

The README gives one command, npm install source-map, run in your project directory. After that you require it as var sourceMap = require("source-map") in Node, or read window.sourceMap in a browser build.

### What is a source map, in the sense this library uses the term?

It is the side file format that records how generated code corresponds to original source positions. The README describes the library as one that generates and consumes the source map format, and links to a separate specification document for the format itself.

### How do I use mozilla/source-map to look up an original position?

Load the raw map with SourceMapConsumer.with, then call consumer.originalPositionFor with a generated line and column. The README's example queries line 2, column 28 and gets back a source URL, line 2, column 10 and the name 'n'.

### What is source map support in mozilla/source-map?

The library itself does not install a runtime hook; it exposes SourceMapConsumer, SourceMapGenerator and SourceNode. The README's API list is the full documented surface, and stack-trace patching is left to other packages.

### How do I use a source map in JavaScript with this library?

The README shows loading a raw map object and calling originalPositionFor on the consumer inside SourceMapConsumer.with. The returned object carries the source path, line, column and, when the map records it, the original identifier name.

## Sources

- [Issues](https://github.com/mozilla/source-map/issues)
- [mozilla/source-map on GitHub](https://github.com/mozilla/source-map)
- [README](https://github.com/mozilla/source-map/blob/master/README.md)
- [Releases](https://github.com/mozilla/source-map/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mozilla-source-map