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.

What is the Source Map v3 Fields Reference?

Reference for the Source Map v3 specification JSON fields including version, sources, sourcesContent, names, mappings, sourceRoot and file, with an explanation of how the VLQ-encoded mappings string works. It runs free in your browser on Gera Tools, with nothing uploaded.

Source Map v3 Fields Reference

Name: Source Map v3 Fields Reference
Creator: Gera Tools
License: https://creativecommons.org/licenses/by/4.0/

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.

Field reference at a glance

Field	Required	Type	Purpose
`version`	Yes	Number	Must be `3`; tools reject anything else
`sources`	Yes	Array of strings	Relative paths to original source files
`sourcesContent`	No	Array of strings/null	Inline text of each source; avoids round-trips
`names`	No	Array of strings	Original identifier names for the `names` index
`mappings`	Yes	String	Base64 VLQ-encoded position map
`sourceRoot`	No	String	Prefix prepended to every `sources` entry
`file`	No	String	Name of the generated file this map belongs to
`x_google_ignoreList`	No	Array of indexes	Hints to debuggers to skip these sources (e.g. node_modules)

Decoding a real segment

Take the mappings string from a tiny bundle and pick one segment, for example AAAA. Each letter is a base64 character (0–63). The VLQ scheme groups them into signed integers, where bit 0 is the sign and the remaining bits are the magnitude, and a continuation bit extends to the next character.

AAAA decodes as four consecutive zeros: generated column 0, source index 0 (delta), original line 0 (delta), original column 0 (delta). In other words: the first character of line 1 of generated code maps to column 0 of line 0 of the first source file — a typical starting point for a non-minified output.

A real segment might be SAAA: S in base64 is 18, which VLQ-decodes as the signed value +9 (shift right one to remove the sign bit). That means the generated column is 9 relative to the previous segment, with sources, lines and columns all at delta 0.

Practical 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 such as a CDN origin or repository root, so each sources entry is a short relative path that resolves correctly on both the build machine and the consumer’s debugger.

Include sourcesContent when the original files may not be reachable at debug time — for example in a production deployment where sources are not served. This makes the map self-contained and lets DevTools show original code without a network request.

The x_google_ignoreList extension field (supported in Chrome DevTools and some bundlers) lets you mark source indexes for third-party libraries so the debugger skips through them automatically, surfacing only your own code in stack traces.

Locate the map via a //# sourceMappingURL= comment at the end of the generated file, or a SourceMap HTTP response header. Avoid shipping the comment in a public production bundle if you do not want the source map — and the original code — discoverable by anyone who inspects network traffic.