skip to content

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%

answer

  1. rebuild speed against fidelity
  2. one mapping per line, no columns
  3. each module run through eval
  4. a sourceURL comment names each module
  5. never ship these to production

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.

solid answer

~50 s

Full maps with column-level segments for every token are the slowest to generate and regenerate, and in development a build may rebuild many times a minute. A **line-only** map keeps one mapping per generated line: it is cheaper and still points each line at its source line, but you cannot break on the second statement of a line, and over a minified one-line file it says almost nothing. **Eval-wrapped** output runs each module as a string through `eval()`, named with a `//# sourceURL=` comment and usually carrying its own inline map, so an edit only re-creates that one module's map. The costs: code runs through `eval`, which behaves differently from normal loading and is refused by a content security policy that forbids string evaluation (the fix there is a non-eval map form), and the fastest variants skip earlier stages' maps and show transpiled code. None of these belong in production.

go deeper

for a junior

Recall that development builds often use faster, less precise maps, and that those forms are never meant for production.

for a middle

Explain what line-only maps drop, how eval wrapping makes rebuilds cheap per module, and why a strict script policy needs a non-eval form.

for a senior

Pick the dev map form deliberately: fast enough for the team's rebuild loop, still reaching original source, and switched to a full map when debugging needs columns.

for a principal

Set the shared default for every app's development and production map forms, weighing team feedback loops against the policies each environment enforces.

## Why development maps are different In production a build runs once per release, and accuracy is what matters. In development the build, or the dev server, re-runs on every save, and generating maps is part of every rebuild. A full map has a segment for **every token**, and each one must be composed through any maps from earlier stages. On a large app that work is noticeable, so build tools offer cheaper map forms for development, trading fidelity for speed. ## The main shortcuts | Form | What it records | Build and rebuild cost | What you lose | |---|---|---|---| | Full, column-accurate map | A segment per token, composed through earlier stages | Highest | Nothing | | **Line-only** ("cheap") map | One mapping per generated line | Lower | Column positions, mid-line breakpoints | | **Eval-wrapped** modules with per-module maps | Each module's own map, attached to its eval'd string | Fast rebuilds | Normal script loading; strict policies | | Eval-wrapped with **only a `sourceURL`** | A name for each module, no map | Lowest | Original code: you see transpiled output | | A mode that **ignores earlier stages' maps** | Maps to the transpiled code only | Lower | The original source, whatever the precision | Two different savings are mixed here: line-only maps save **map size and generation time**, while eval wrapping saves **rebuild time**, because each module's map is independent and only the edited module's map is regenerated. ## Line-only maps A line-only map keeps one segment per generated line, pointing at the original line it came from. That is often enough in development, where output is not minified and most lines hold one statement: - a stack position still lands on the right original line, provided the map reaches the original source; - stepping line by line still works; - the map is much smaller and faster to build. What it cannot do: 1. distinguish two statements, or two calls, on the same line, so a breakpoint on the second one is impossible; 2. help with **minified** output, where nearly everything sits on one line, so every position maps to the same place; 3. regain columns later: if an earlier stage emitted a line-only map, composition caps the whole chain at line precision. ## Eval-wrapped modules In this form the build ships each module's code as a **string** and runs it with `eval()`. Each string ends with a `//# sourceURL=` comment, which ECMA-426 uses as the source origin of code evaluated from a string, so developer tools list every module as its own file. A richer variant also appends the module's own map as a `data:` URL. Because each module is self-contained, an edit replaces one string and one small map instead of regenerating a map for a whole chunk. The costs are real, though: - **Code runs through `eval`.** That differs from normal script loading and is something production code should never depend on. - **Strict content security policies refuse it.** A policy that disallows evaluating strings blocks this output entirely (the details of that breakage belong to the policy topic). The build-side fix is to choose a **non-eval** form, separate or inline map files, for any environment that enforces such a policy. - **The cheapest variants show transpiled code.** A form with only a `sourceURL`, or one that skips the maps of earlier stages, is fast precisely because it does less mapping. ## Making the choice - For everyday development, a fast form that still reaches the **original source** at line precision is a common default. - When you need to break inside a long expression, or debug the minified output itself, switch to a **full** map, accepting slower rebuilds. - Any environment that enforces a strict script policy, and every production build, needs a **non-eval** form. - Dependencies can be hidden from stepping in any form by listing them in the map's `ignoreList`; some dev servers do this for dependency folders by default. ## Common mistakes - Shipping a development map form to production because the dev build "works". - Blaming the browser when a cheap map cannot place a breakpoint mid-line. - Assuming eval-wrapped output behaves exactly like the production bundle.

  • Why does eval-wrapped output rebuild faster than a single map for the whole bundle?
    Each module carries its own small map attached to its own evaluated string, so an edit regenerates one module's code and map and leaves the others untouched. A single map for a chunk has to be re-encoded, and its delta-encoded segments recomputed, whenever any module in that chunk changes.
  • When is a line-only map a poor choice even in development?
    When the output being debugged puts several statements on one line, such as minified or heavily generated code, or when you need a breakpoint inside a long expression or a chained call. In those cases every position on the line collapses to one mapping, and only a column-accurate map helps.

  • Line-only maps are fine for production because errors still show a line.
  • Eval-wrapped modules behave exactly like the production bundle at run time.
  • A cheap development map can still set breakpoints on any column.
  • A content security policy has no effect on how dev maps are delivered.
  • Every development map form always shows the original TypeScript source.