Scope

This Standard defines the source map format, used by different types of developer tools to improve the debugging experience of code compiled to JavaScript, WebAssembly, and CSS.

Conformance

A conforming source map document is a JSON document that conforms to the structure detailed in this specification.

A conforming source map generator should generate documents which are conforming source map documents, and can be decoded by the algorithms in this specification without reporting any errors (even those which are specified as optional).

A conforming source map consumer should implement the algorithms specified in this specification for retrieving (where applicable) and decoding source map documents. A conforming consumer is permitted to ignore errors or report them without terminating where the specification indicates that an algorithm may optionally report an error.

References

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

Notational Conventions

This specification follows the same notational conventions as defined by ECMA-262 (Notational conventions), with the extensions defined in this section.

Terms and Definitions

For the purposes of this document, the following terms and definitions apply.

generated code

code which is generated by the compiler or transpiler.

original source

source code which has not been passed through a compiler or transpiler.

source map URL

URL referencing the location of a source map from the generated code.

column

zero-based indexed offset within a line of the generated code, computed as UTF-16 code units for JavaScript and CSS source maps, and as byte indices in the binary content (represented as a single line) for WebAssembly source maps.

That means that “A” (`LATIN CAPITAL LETTER A`) measures as 1 code unit, and “🔥” (`FIRE`) measures as 2 code units. Source maps for other content types may diverge from this.

base64 VLQ

A base64 VLQ is a base64-encoded variable-length quantity, where the most significant bit (the 6th bit) is used as the continuation bit, and the “digits” are encoded into the string least significant first, and where the least significant bit of the first digit is used as the sign bit.

A base64 VLQ adheres to the following lexical grammar:

JSON values utilities

While this specification's algorithms are defined on top of ECMA-262 internals, it is meant to be easily implementable by non-JavaScript platforms. This section contains utilities for working with JSON values, abstracting away ECMA-262 details from the rest of the document.

A JSON value is either a JSON object, a JSON array, a String, a Number, a Boolean, or *null*.

A JSON object is an Object such that each of its properties:

• is a data property,
• has a String key,
• has JSON value value.

A JSON array is a JSON object such that:

• it has a property whose key is *"length"* and whose value is a Number,
• all its other properties' keys are integer indices.

Position types

Source map format

A source map is a JSON document containing a top-level JSON object with the following structure:

  {
    "version" : 3,
    "file": "out.js",
    "sourceRoot": "",
    "sources": ["foo.js", "bar.js"],
    "sourcesContent": [null, null],
    "names": ["src", "maps", "are", "fun"],
    "mappings": "A,AAAB;;ABCDE",
    "ignoreList": [0]
  }
  

• The version field shall always be the number 3 as an integer. The source map may be rejected if the field has any other value.
• The file field is an optional name of the generated code that this source map is associated with. It's not specified if this can be an URL, relative path name, or just a base name. Source map generators may choose the appropriate interpretation for their contexts of use.
• The sourceRoot field is an optional source root string, used for relocating source files on a server or removing repeated values in the sources entry. This value is prepended to the individual entries in the sources field.
• The sources field is a list of original sources used by the mappings field. Each entry is either a string that is a (potentially relative) URL or *null* if the source name is not known.
• The sourcesContent field is an optional list of source content (i.e. the original source) strings, used when the source cannot be hosted. The contents are listed in the same order as in the sources field. Entries may be *null* if some original sources should be retrieved by name.
• The names field is an optional list of symbol names which may be used by the mappings field.
• The mappings field is a string with the encoded mapping data (see section ).
• The ignoreList field is an optional list of indices of files that should be considered third party code, such as framework code or bundler-generated code. This allows developer tools to avoid code that developers likely don't want to see or step through, without requiring developers to configure this beforehand. It refers to the sources field and lists the indices of all the known third-party sources in the source map. Some browsers may also use the deprecated `x_google_ignoreList` field if `ignoreList` is not present.

Index source map

To support concatenating generated code and other common post-processing, an alternate representation of a source map is supported:

  {
    "version" : 3,
    "file": "app.js",
    "sections": [
      {
        "offset": {"line": 0, "column": 0},
        "map": {
          "version" : 3,
          "file": "section.js",
          "sources": ["foo.js", "bar.js"],
          "names": ["src", "maps", "are", "fun"],
          "mappings": "AAAA,E;;ABCDE"
        }
      },
      {
        "offset": {"line": 100, "column": 10},
        "map": {
          "version" : 3,
          "file": "another_section.js",
          "sources": ["more.js"],
          "names": ["more", "is", "better"],
          "mappings": "AAAA,E;AACA,C;ABCDE"
        }
      }
    ]
  }
  

The index map follows the form of the standard map. Like the regular source map, the file format is JSON with a top-level object. It shares the version and file field from the regular source map, but gains a new sections field.

The sections field is an array of objects with the following fields:

• offset field is an object with two fields, `line` and `column`, that represent the offset into generated code that the referenced source map represents.
• map field is an embedded complete source map object. An embedded map does not inherit any values from the containing index map.

The sections shall be sorted by starting position and the represented sections shall not overlap.

Retrieving source maps

sourcemap: <url>

let a = `
//# sourceMappingURL=foo.js.map
// `

)]}'garbage here
{"version": 3, ...}

{"version": 3, ...}

Operations on source map records

After decoding a source map, source map consumers can use the resulting Decoded Source Map Records to look up position information for debugging or other use cases. This section describes the behaviour of typical operations that may be supported by source map consumers.

The GetOriginalPositions operation may be used to query the positions in an original source that correspond to a position in the generated code. For example, this can be used in a debugger to navigate from the generated code to the original source based on a user's mouse click.