What is a TypeScript Map file?

There are two types of .map files that are most common in Typescript. One is Source Map (.js.map) and the other is Declaration Map (.d.ts.map). I will explain both in detail one by one.

Source Maps: .js.map

Source map (.js.map) files contain mapping definitions that link each piece of your generated Javascript code back to the specific line and column of the corresponding Typescript file. The mapping definitions in these files are in JSON format.

When source maps are enabled, while debugging, Visual Studio Code and Chrome DevTools will show your Typescript code instead of the generated complex Javascript code.

Why use source maps?

In production apps, for example, we use build tools like Rollup to remove dead code, Prepack to eliminate and replace the code with computations that can be evaluated at compile time instead of run time, then minify the code with Uglify. And not to mention the complexity of the already transpiled Javascript code. So, the resulting code can be much different than the code you actually wrote. Therefore it is recommended to use source maps, it makes debugging very easy because you get to step through your original source code.

Process monitoring, error monitoring, logging and stack tracing tools like Sentry, Bugsnag, PM2, Winston also use source maps for mapping lines and columns in Javascript exception stack traces back to Typescript.

How to use source maps?

You can enable source maps either by using --sourceMap option while compiling or by specifying it in compilerOptions in tsconfig.json file of your project, like following:

{
  "compilerOptions": {
    ...
    "sourceMap": true,
    "outDir": "./out"
  }
}

Security note for source maps:

If you want to achieve some security by obfuscating your browser code, you may want to exclude source maps from browser code in your production app.

Declaration Maps: .d.ts.map

Declaration map (.d.ts.map) files also known as declaration source maps, contain mapping definitions that link each type declaration generated in .d.ts files back to your original source file (.ts). The mapping definition in these files are in JSON format.

This is helpful in code navigation. You’ll be able to use editor features like “Go to Definition” and Rename to transparently navigate and edit code across sub projects when you have split a big project into small multiple projects using project references.

To enable declaration maps, specify the following two options in tsconfig.json file of your project:

{
  "compilerOptions": {
    ...
    "declaration": true,
    "declarationMap": true
  }
}

That's it! Hope that helps.


.map files are source map files that let tools map between the emitted JavaScript code and the TypeScript source files that created it. Many debuggers (e.g. Visual Studio or Chrome's dev tools) can consume these files so you can debug the TypeScript file instead of the JavaScript file.

This is the same source map format being produced by some minifiers and other compiled-to-JS languages like CoffeeScript.


A source map is basically what it says, a map from one language to another, so the debugger can run the JavaScript code but show you the line that actually generated it.

For practical debugging purposes:

What the source map lets you do is set a breakpoint on the TypeScript file and then debug the code. This can be done in Chrome and Firefox. Somewhat confusingly, the debugger behaviour in Chrome is that when the breakpoint is reached, the '.js' file is actually shown (stopped at the breakpoint).

As of today, the Firefox debugger will display the actual TypeScript file when it breaks. See the below reference:

http://www.gamefromscratch.com/post/2014/05/27/TypeScript-debugging-in-Visual-Studio-with-IE-Chrome-and-Firefox-using-Source-Maps.aspx)

(this also shows how Visual Studio can be configured to create the source map)

To understand how a source map works, you can read the section 'The anatomy of a source map' here:

https://www.html5rocks.com/en/tutorials/developertools/sourcemaps/

Tags:

Typescript

Recent Posts