skip to content

Source Maps

A source map ties each position in shipped code back to the original file, line and name through its mappings, sources and names fields. Interviewers ask how to debug minified errors safely.

on this pageshow

questions

6

In a web build, what is a source map for, and how do browser developer tools find the map for a shipped file?

level: juniorimportance: must knowfreq 24%

answer

  1. shipped code is not what you wrote
  2. generated position to original position
  3. JSON, version 3, one standard
  4. a last-line comment in the file
  5. a response header, which takes precedence

basics

~20 s

A source map is a JSON file that maps positions in shipped, transformed code back to the original file, line, column and name. Developer tools find it through a sourceMappingURL comment at the end of the file or a SourceMap response header.

solid answer

~40 s

Browsers run code a build has transpiled, bundled and minified, so a position such as line 1, column 48210 of `app.3f9a.js` means nothing to the person who wrote the code. A source map is a JSON document (version 3, standardised as ECMA-426) whose `mappings` field ties positions in that generated file to positions in the `sources` it came from, with original identifiers in `names`. The page runs exactly the same without it; developer tools read it to show the original files, set breakpoints in them and translate positions. They find it through a last-line comment, `//# sourceMappingURL=app.3f9a.js.map` in JavaScript or `/*# sourceMappingURL=... */` in CSS, resolved relative to the file's own URL, or through a `SourceMap: <url>` HTTP response header, which wins when both are present.

go deeper

for a junior

Say what a source map is for in one breath: it maps positions in shipped code back to the original file, line and name. Then name both ways a tool finds it: the comment and the header.

for a middle

Explain that the link is a URL resolved against the generated file, that the header beats the comment, and that the page itself never needs the map. Mention that CSS uses the same format with a block comment.

for a senior

Use the linking rules to reason about deployment: a header can point some requests at a map the file never mentions, and a missing link means tools have nothing to follow at all.

for a principal

Frame the map as a debugging artefact with an audience: who should be able to follow the link, and whether the build's link mechanism, comment or header, lets you decide that per environment.

## Why shipped code needs a map The code a browser runs is rarely the code a developer wrote. A web build typically does several things to it before it is deployed: - **Transpiles** it: TypeScript loses its types, JSX becomes function calls, newer syntax is rewritten for older engines. - **Bundles** it: hundreds of source modules are merged into a few output files. - **Minifies** it: whitespace and comments go, local variables get one-letter names, and the whole file often ends up on a single line. The result is fast to download but hard to read. When a breakpoint, an error position or a debugger step lands on line 1, column 48210 of `app.3f9a.js`, nobody can tell which function in which original file that was. A **source map** answers that question. ## What a source map is A source map is a **JSON document** whose format is standardised as **ECMA-426**. The current format is version 3, and its `version` field must be the number `3`. In outline: - `sources` lists the original files the output was built from. - `mappings` is an encoded string that pairs positions in the **generated** file (line and column) with positions in one of those sources. - `names` lists original identifiers, so a minified `g` can be shown as `greet`. - Optional fields such as `sourcesContent` (the original text itself) and `ignoreList` (sources to treat as third-party) refine it. The map is **data for tools, not code for the page**. The browser does not need it to run the bundle, and loading one changes nothing about how the page behaves. Developer tools use it to show the original files in their source panel, let you set breakpoints in the original code, and translate generated positions into original ones. Error-reporting tooling uses the same file for the same translation. The format also covers **CSS**: a stylesheet produced from a preprocessor or a CSS bundle can carry a map back to the files it came from. ## How a tool finds the map ECMA-426 defines two ways to link a generated file to its map: 1. **An annotation comment** in the generated file itself, conventionally its last line. In JavaScript it is `//# sourceMappingURL=app.3f9a.js.map`; CSS has only block comments, so a stylesheet uses `/*# sourceMappingURL=app.css.map */`. The older `//@` prefix is still accepted, but `//#` is the preferred form. 2. **An HTTP response header**, `SourceMap: <url>`, sent with the generated file. It needs server support but leaves the file's contents untouched. Its old name, `X-SourceMap`, is deprecated. When both are present, **the header has precedence** and its URL is the one used. A relative URL in either place is resolved against the generated file's own URL, so the comment `app.3f9a.js.map` in a file served from `/assets/app.3f9a.js` points at `/assets/app.3f9a.js.map`. The entries in `sources` are then resolved relative to the map's own URL, after any `sourceRoot` prefix has been prepended. The URL may also be a `data:` URL, which puts the whole map inside the generated file: that is an **inline** map, while a separate `.map` file is an **external** one. | Situation | What developer tools can do | |---|---| | File linked to a reachable map | Show original files, names and positions; set breakpoints in the original code | | File linked to a map that cannot be fetched | Fall back to the generated code; the page still runs | | File with no comment and no header | Nothing to follow, unless someone attaches a map by hand | ## What a map does not do - It does not change the shipped code or make it run like the original. Minified names stay minified at run time. - It does not have to sit next to the bundle under a matching name. The link is a URL and can point anywhere the tool can reach. - It is not only for JavaScript. The same format and the same comment convention apply to CSS (and WebAssembly carries the URL in a custom section). ## Why interviewers ask it The question checks whether a candidate understands that debugging production code is a translation from generated positions to original ones, and that the link is explicit: a comment or a header, not a naming convention. Every later question about which maps to emit, whether to publish them and how to keep them accurate through a build chain rests on that.

  • If a file's sourceMappingURL comment and its SourceMap response header name different maps, which one do developer tools use?
    The header. ECMA-426 gives the `SourceMap` HTTP header precedence over a source annotation: when both are present, the header's URL is the one used to fetch the map. That lets a server point some requests at a different map, or at one in a restricted location, without changing the file's contents.
  • Does linking an external source map make the page slower for ordinary users?
    Not meaningfully. The comment adds a few bytes, and running the page never requires the map, so an ordinary page load has no reason to fetch it. An inline map is different: it is a `data:` URL inside the file, so every user downloads the whole map with every copy of the bundle.
  • How are the file names listed inside a map resolved?
    Each entry in `sources` gets the `sourceRoot` prefix if one is set; if the result is still not an absolute URL, it is resolved relative to the map's own URL, the way a script's `src` resolves against the page. Tools then fetch each source from there, unless `sourcesContent` already carries its text.

  • A source map makes the minified code run like the original source.
  • The browser needs the source map before it can execute the bundle.
  • The map is found only if it sits beside the bundle with the same name.
  • Source maps exist only for JavaScript, so stylesheets cannot be mapped.
  • When a file has both a comment and a SourceMap header, the comment wins.
open as a page

When a web build emits source maps, how do inline, external and hidden maps differ in what reaches the browser, and when does each fit?

level: middleimportance: must knowfreq 15%

basics

~20 s

An inline map is a data URL inside the shipped file, so every user downloads it. An external map is a separate file the comment names. A hidden map is that file emitted without the comment, so nothing points at it.

open as a page

In a source map, what do the `sources`, `sourcesContent`, `names`, `mappings` and `ignoreList` fields hold, and how is `mappings` encoded?

level: middleimportance: should knowfreq 10%

basics

~10 s

sources lists original files, sourcesContent their optional full text, names original identifiers, ignoreList the indices of third-party sources. mappings is a string of Base64 VLQ deltas: semicolons separate generated lines, commas separate segments.

open as a page

Why would a build's source maps point at transpiled JavaScript instead of the TypeScript files when a hotel-booking app transpiles, bundles and minifies, and how do you fix it?

level: seniorimportance: should knowfreq 5%

basics

~20 s

Each stage maps only its own input to its output, so the final map reaches the TypeScript only if every stage reads the previous map and emits a composed one. A stage that drops it makes its own input the new original.

open as a page

A security review finds a hotel-booking app's source maps publicly reachable; what do `sourcesContent`, `sources` and `names` reveal, and how do you keep maps private yet useful?

level: seniorimportance: should knowfreq 8%

basics

~20 s

Public maps make the original code readable: sourcesContent holds every file's full text with comments, sources the project's file layout and names its original identifiers. Keep them off the public deploy, or behind access control, while internal tools still read them.

open as a page

Why would a development build emit source maps that are line-only or eval-wrapped rather than column-accurate, and what does each shortcut cost?

level: middleimportance: nice to knowfreq 6%

basics

~20 s

Both trade accuracy for rebuild speed. A line-only map keeps one mapping per line, so it is smaller and quicker to build but loses columns. Eval-wrapped modules carry their own maps, so a rebuild only regenerates the edited module's map.

open as a page