skip to content

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%

answer

  1. each stage knows only its input
  2. read the input map, emit a combined one
  3. the dropped link becomes the new original
  4. check each stage's sources list
  5. precision is capped by the weakest stage

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.

solid answer

~50 s

A transpiler, a bundler and a minifier each see only their input, so each can map its output back to that input and no further. To reach the TypeScript, every stage must **read the incoming map** and **emit a composed one**, translating each position through the previous map. When one link is missing, the stage that dropped it becomes the new 'original': here the bundler, or whatever ran after the transpiler, ignored the transpiler's maps or the transpiler emitted none, so the final map's `sources` list `.js` files and `sourcesContent` shows transpiled code. Find it by reading each stage's output map, then enable map output before it and input-map reading in it. Two quieter failures: a stage that moves code but passes the old map through gives right files at wrong lines, and a line-only map anywhere caps the chain at line precision.

go deeper

for a junior

Remember that each build stage makes its own map and that the final map only reaches your original files if every stage passes its map on.

for a middle

Explain composition: each stage reads the incoming map and translates its positions through it, and the sources list shows where the chain ends.

for a senior

Diagnose by reading each stage's sources, separate a dropped link from a stale map that gives wrong lines, and add a build check so a cut chain cannot ship silently.

for a principal

Treat map fidelity as a property of the whole pipeline: decide which stages must carry maps, how precise they must be, and how the shared build config verifies it.

## One map per stage A typical production build for a TypeScript single-page app is a **chain**: a transpile step turns `.ts` into JavaScript, a bundler merges modules into chunks, and a minifier compresses each chunk. Each stage is a separate transformation with its own view of the world: - the transpiler can map its JavaScript output back to the `.ts` file it read; - the bundler can map each chunk back to the modules it received, which are the transpiler's `.js` output; - the minifier can map the minified chunk back to the unminified chunk it received. None of them, alone, can map the final file to the TypeScript. That map exists only if the stages **compose** their maps as the code moves along. ## How composition works A stage that supports it does the following: 1. It obtains the **input map**, either from the input file's own `sourceMappingURL` comment (often an inline map) or because the build passes the map in alongside the code. 2. It performs its transformation and builds its **own map**, from its output back to its input. 3. For every segment of its own map, it looks up the input position in the input map and replaces it with the **original position** that map gives, carrying the original `sources`, `names` and `sourcesContent` across. 4. It emits the result: a single map from its output straight back to the first stage's sources. Done at every step, the last map in the chain points from the minified bundle to the `.ts` files, with original names. Several tools document exactly this: a minifier that accepts an input map, and bundlers that compose the maps returned by each per-file transform, which reach the original only if every transform supports maps. ## What a broken link looks like | What went wrong | What the final map shows | |---|---| | A stage ignored the incoming map | `sources` lists that stage's input files (here, transpiled `.js`); frames point at transpiled code | | The first stage emitted no map at all | The same: the chain can only start at the first stage that produced one | | A stage moved code but passed the old map through unchanged | The right original files, at shifted, wrong lines and columns | | One stage produced a line-only map | Line positions at best; column information cannot be recovered later | | The map came from a different build | Positions that match nothing, or match the wrong code | The hotel-booking symptom, frames in transpiled JavaScript, is the first or second row. The **`sources` array is the tell**: if it lists `dist/tmp/booking.js` rather than `src/booking.ts`, the chain was cut right after the transpiler. ## Finding and fixing the broken stage 1. **Read the final map's `sources`** to see which stage's input it ends at. 2. **Emit each stage's intermediate map** and read its `sources` too. The first map whose sources are not the `.ts` files marks the stage that dropped the link. 3. **Check both sides of that link.** Did the earlier stage write a map at all, and was it inline or written where the next stage looks for it? Does the later stage have input-map reading switched on? 4. **Rebuild and re-check positions**, not just file names: open a known function in developer tools and confirm the line and column match the TypeScript. For a stage you write yourself, such as a small custom transform, the rule is the same: if it changes code, it must return a map for that change; if it returns nothing while moving code, the chain silently carries a stale map through. ## Composition is not concatenation ECMA-426 also has an **index map**, whose `sections` array places complete maps side by side at offsets in the generated file. That serves output glued together from independently mapped pieces. It does **not** chain stages: an index map can only describe pieces side by side, not one transformation on top of another. ## Pitfalls worth naming - **Precision only goes down.** A low-resolution map anywhere in the chain limits the result; one tool's docs warn that a low-resolution map "can compose down to nothing". - **Speed shortcuts cut the chain.** Some fast development map modes skip earlier stages' maps on purpose and show transpiled code, an acceptable trade in development and a defect in production. - **Tests miss it.** The build succeeds and the app works; only a check of the maps themselves catches a cut chain, so it belongs in the build's own verification.

  • How can a single build step check that its maps still reach the original sources?
    After the build, read each emitted map's `sources` and fail if any entry is an intermediate file, such as a temporary `.js` output, rather than a source path. A stronger check decodes a few known positions, for example a named function, and compares them with the original file's line and column.
  • Why does a line-only map early in the chain hurt even if the minifier emits column-accurate maps?
    Composition translates each position through the earlier map. If that map holds one mapping per line, every column on the line resolves to the same original position, and no later stage can invent the missing detail. The result is line precision at best, which on a one-line minified file means very little.
  • Is an index map a way to compose the maps of successive build stages?
    No. An index map's `sections` place complete maps side by side at offsets in one generated file, which suits output concatenated from separately mapped pieces. Chaining a transformation on top of another needs real composition, where each position is translated through the previous map.

  • The minifier's map automatically points at the TypeScript, whatever earlier stages emitted.
  • If the final map lists .js files, the minifier is the stage to blame.
  • A stage that moves code can safely pass the incoming map through unchanged.
  • An index map with sections chains the maps of successive build stages.
  • Later stages can restore column precision that an earlier line-only map dropped.