sourceMap
Generates .js.map files so debuggers and stack traces point back at the original source.
"sourceMap": boolean // default: false- Added in TypeScript 1.5
Parameters
| Parameter | Type | Description |
|---|---|---|
$sourceMapoptional | boolean= false | Emit a separate .js.map file next to each JavaScript output. |
$inlineSourceMapoptional | boolean= false | Embed the map as a base64 data URI at the end of the .js file instead of writing a separate .map. Mutually exclusive with sourceMap. |
$inlineSourcesoptional | boolean= false | Include the original .ts text inside the map. Requires sourceMap or inlineSourceMap to be enabled. |
$sourceRootoptional | string | Root path or URL where the debugger should look for the original sources; written verbatim into the map. |
$mapRootoptional | string | Location where the debugger should look for the .map files instead of their default emitted location. |
Return value
booleanA .js.map file per emitted .js file, plus a //# sourceMappingURL comment referencing it.
Errors
The compiler errors when sourceMap and inlineSourceMap are both set, and when inlineSources is set without either of them.
Changelog
- PHP 1.5inlineSourceMap and inlineSources added alongside sourceMap.
sourceMap writes a .js.map next to every emitted file and appends a //# sourceMappingURL= comment pointing at it. Anything that understands source maps — Chrome DevTools, the VS Code debugger, Node with --enable-source-maps, Sentry — then reports positions in your .ts instead of in the generated JavaScript. Without it, a breakpoint set on a .ts line has nothing to bind to and a production stack trace names a column in a file you never wrote.
Choosing between the three flags
inlineSourceMap embeds the map as a base64 comment inside the .js. Use it when the map file cannot be served or would get lost — inside a bundler pipeline, a serverless artefact, a test runner that only reads one file. It is mutually exclusive with sourceMap; setting both is a compiler error.
inlineSources puts the original TypeScript text into the map, so the debugger can show source it cannot fetch from disk. It requires one of the other two.
What trips people up
A map only works if the runtime can find the source. If you ship dist/ without src/, external maps resolve to nothing and you see the compiled file anyway — that is what inlineSources fixes. And maps expose your source: shipping them to a public bundle publishes your pre-compilation code.
Example
// src/parse.ts — built with { "sourceMap": true, "outDir": "dist" }
function parseAmount(input: string): number {
const n = Number(input);
if (Number.isNaN(n)) {
throw new Error(`not a number: ${input}`);
}
return n;
}
try {
parseAmount("12abc");
} catch (err) {
const e = err as Error;
console.log(e.message);
// Raw frame: dist/parse.js:4. With the .js.map and a map-aware
// runtime the same frame reads src/parse.ts:4.
console.log(String(e.stack).split("\n")[0]);
}When to use it
- Setting breakpoints on .ts lines in the VS Code debugger against compiled output.
- Making Node stack traces readable in production with --enable-source-maps.
- Uploading maps to an error tracker so reported frames name the original file and line.
- Using inlineSourceMap plus inlineSources for a serverless bundle where extra files are not deployed.
Frequently asked questions
Why are my breakpoints not hitting in TypeScript?
Almost always because sourceMap is off, or the .js.map cannot be found next to the .js it names. Set "sourceMap": true, rebuild, and confirm dist/x.js ends with a //# sourceMappingURL=x.js.map comment and that x.js.map exists. If you deploy dist/ without src/, add "inlineSources": true so the map carries the source text itself.
Should I use sourceMap or inlineSourceMap?
Use sourceMap for normal builds and inlineSourceMap only when a separate .map file would be dropped by the pipeline. They cannot both be enabled — the compiler rejects the combination. inlineSourceMap makes each .js substantially bigger because the whole map is base64-encoded into it.
Is it safe to ship source maps to production?
It exposes your pre-compilation source to anyone who opens DevTools, and with inlineSources the source text itself is in the bundle. The common compromise is to build with maps, upload them to your error tracker, then strip them from the public assets so stack traces stay readable server-side without publishing the code.
More examples
Debuggable build output
Each dist/x.js gets a dist/x.js.map, and the map carries the .ts text itself. Because the sources are inside the map, the debugger renders the original file even on a machine that only has dist/ — the usual situation in a container or a deployed function.
{
"compilerOptions": {
"outDir": "dist",
"rootDir": "src",
"sourceMap": true,
"inlineSources": true
}
}What inlineSourceMap emits
With inlineSourceMap the map is appended to the JavaScript as a base64 data URI rather than written to index.js.map. One file carries everything, at the cost of a much larger .js — which is why it is a development or bundling choice rather than something you ship to browsers.
"use strict";
const helloWorld = "hi";
console.log(helloWorld);
//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMi...
Discussion