What does the mappings field actually contain?

It is a single string of base64 VLQ-encoded numbers. Semicolons separate lines of generated code, commas separate segments within a line, and each segment is 1, 4, or 5 VLQ values describing the generated column and, optionally, the source file index, original line, original column, and a names index.

Is sourcesContent required?

No, it is optional. When present it is an array, parallel to sources, holding the original source text inline so a debugger does not have to fetch the original files separately. Omitting it keeps the map smaller but requires the originals to be reachable.

Why are the VLQ values stored as deltas?

Every field after the generated column is encoded relative to the previous segment's value, and the generated column resets each line. Delta encoding keeps the numbers small, which keeps their VLQ representation short, dramatically shrinking the mappings string for large files.

What is sourceRoot for?

sourceRoot is an optional prefix prepended to every entry in the sources array to resolve them. It lets you store short relative paths in sources and supply the common base URL once, for example a CDN or repository root.

How does a browser find the source map?

Either a trailing //# sourceMappingURL=app.js.map comment in the generated file, or a SourceMap HTTP response header pointing at the map. The browser then fetches that JSON and uses the version field to confirm it understands the format, which must be 3.

Source Map v3 Fields Reference

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

What a source map is

A source map is a JSON file that lets debuggers translate positions in generated (minified, transpiled, or bundled) code back to positions in your original source. The current format is Source Map v3. Its most important and most cryptic field is mappings: a compact, base64 VLQ-encoded string that pairs every span of generated output with the original file, line, column, and name it came from.

How it works

The JSON has a small, fixed set of top-level fields — version, sources, names, mappings, and a few optional helpers. The mappings string is read as follows:

A ; advances to the next line of generated code (the generated column counter resets to 0).
A , separates segments within a line.
Each segment is 1, 4, or 5 VLQ values: generated column, then source index, original line, original column, and optionally a names index.
Every value except the generated column-at-start is a delta from the previous occurrence, which keeps the numbers — and so the string — tiny.

The reference lists each field; the decoder below expands a single segment’s base64 VLQ values into plain integers so you can see the mechanism.

Tips and notes

version must be 3 — anything else means a tool will refuse the map. Keep sources paths consistent and use sourceRoot to factor out a common prefix. Inline sourcesContent when the originals may not be reachable at debug time. The map is located via a //# sourceMappingURL= comment or a SourceMap response header; never ship the comment to production if you do not want maps discoverable.