Map runtime errors to TypeScript
Debugging transpiled application code
TypeScript · Const
sourceMap
sourceMap enables source-map generation for emitted JavaScript. Debuggers can use the generated .js.map files to show the original TypeScript source while the JavaScript runs.
How it works
Set sourceMap to true in compiler options to emit a separate source-map file alongside each generated JavaScript file. The generated JavaScript includes a mapping comment, enabling debuggers and similar tools to relate emitted code to the original TypeScript.
Syntax
{
"compilerOptions": {
"sourceMap": true
}
}Parameters
| Name | Type | Description |
|---|---|---|
sourceMap | boolean | Whether to emit source-map files for generated JavaScript. |
Returns
When enabled, emits .js.map or .jsx.map files next to generated JavaScript and adds a source-map comment to the JavaScript.
Key points
sourceMapis a boolean compiler option that turns on source-map generation.- The emitted maps let debugging tools present TypeScript locations instead of only generated JavaScript locations.
- A separate map is produced beside the corresponding JavaScript output, using a
.js.mapor.jsx.mapsuffix. - Generated JavaScript includes a comment that tells external tools where to find its source map.
- The compiler option accepts a boolean value and defaults to
false. - Use
sourceMapfor JavaScript output anddeclarationMapseparately when declaration-file navigation also needs mappings.
Common mistakes
- For published libraries, source maps provide the most useful debugging experience when the original TypeScript source files are shipped as well.
Example: Emit a source map
// tsconfig.json
{
"compilerOptions": {
"target": "ES2020",
"module": "CommonJS",
"outDir": "dist",
"sourceMap": true
}
}
// greet.ts
export function greet(name: string) {
return `Hello, ${name}`;
}Compile with tsc -p tsconfig.json; TypeScript emits JavaScript plus greet.js.map, allowing a debugger to map generated code back to greet.ts.
When to use it
Improve consumer debugging
Publishing a TypeScript library with its source files
Connect emitted code to authoring code
Investigating generated JavaScript in browser or debugger tooling
Interview questions
QWhat does the sourceMap option do?
sourceMap is a boolean compiler option that causes TypeScript to emit source-map files for generated JavaScript. The maps let debuggers and other tools show the original TypeScript while executing the emitted code.
Follow-up: How can maps be embedded instead? Use inlineSourceMap, which puts the map content into the emitted JavaScript rather than writing a separate .js.map file.
QWhat files and metadata does enabling sourceMap produce?
With sourceMap: true, each emitted .js file has a neighboring .js.map or .jsx.map file. The JavaScript also contains a source-map comment that points external tools to that map.
Follow-up: What related option maps declaration files? declarationMap emits maps for .d.ts files so navigation can lead back to the original TypeScript source.
QWhy enable source maps in a large codebase?
The option is useful during debugging because it maps generated JavaScript locations to the original TypeScript source. It does not itself alter the runtime JavaScript behavior; it supplies debugging metadata.
Follow-up: How can debugger source locations be customized? sourceRoot specifies a path or URL where the debugger should locate the TypeScript files.
Related
inlineSourceMapinlineSourcessourceRootdeclarationMapmapRoot