Understanding Source Maps: Simplifying Debugging

Photo by cottonbro studio

Introduction

Today, we are talking about source maps, a crucial tool in modern web development that makes debugging significantly easier.

What is a Source Map?

Definition of the Source Map from Firefox official docs:

A source map is a file that maps from the transformed source to the original source, enabling the browser to reconstruct the original source and present the reconstructed original in the debugger.

Debugging with Source Maps

Let's dive into two common debugging scenarios and see how source maps can simplify the process.

• Debugging Transpiled code

In the past, websites/web applications used to be created with simple HTML, CSS, and Javascript. However, in the present day, we are usually building these web applications with various development tools such as:

• JavaScript frameworks: Angular, React, Vue, Svelte, etc.
• High-level programming languages: TypeScript, Flow, etc.
• CSS preprocessors: SCSS, LESS, PostCSS, etc.

These tools then transpile our code into standard HTML, JavaScript, and CSS that browsers can understand.

Without source maps, debugging the transpiled code can be cumbersome. However, with source maps, the debugging experience becomes seamless.

• Debugging minified code:

Minifying is a common practice for optimizing production code. (for example, using Terser to minify and mangle JavaScript).

However, minification often obfuscates the code, making it challenging to debug. Source maps come to the rescue again by mapping the minified code back to its original, unminified form.

Generating source maps

Source maps are files with names ending with .map (for example, example.min.js.map and styles.css.map). They can be generated by most build tools, for example, Typescript, Webpack, Rollup, etc.

Some tools include source maps by default, while others may need additional configuration to produce them.

• Demo

Here, we will be creating a web page with Typescript code transpiled into Javascript to log "Hello World" in the browser console when a button is clicked. To generate an error, button has not been included in the HTML file.

This is the Typesript configuration file (tsconfig.json) of the project and as we can see we have enabled the source map generation option in line 6.

	{
	"compilerOptions": {
	"target": "es2016", /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
	"module": "commonjs", /* Specify what module code is generated. */
	"rootDir": "src", /* Specify the root folder within your source files. */
	"sourceMap": true, /* Create source map files for emitted JavaScript files. */
	"outDir": "dist", /* Specify an output folder for all emitted files. */
	"removeComments": true, /* Disable emitting comments. */
	"esModuleInterop": true, /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
	"forceConsistentCasingInFileNames": true, /* Ensure that casing is correct in imports. */
	"strict": true, /* Enable all strict type-checking options. */
	"skipLibCheck": true /* Skip type checking all .d.ts files. */
	}
	}

view raw tsconfig.json hosted with ❤ by GitHub

The complete code of this project can be found here

qur786 / Introduction-to-source-map

Introduction to Source Map

View on GitHub

When we transpile Typescript file index.ts into Javascript, besides index.js file it also creates one more file called index.js.map. This is a source map that a browser can use to recreate index.ts file from index.js.

	"use strict";
	const button = document.getElementById("button");
	button.addEventListener("click", () => {
	console.log("Hello world!");
	});
	//# sourceMappingURL=index.js.map

view raw index.js hosted with ❤ by GitHub

	{
	"version": 3,
	"file": "index.js",
	"sourceRoot": "",
	"sources": [
	"../src/index.ts"
	],
	"names": [],
	"mappings": ";AAAA,MAAM,MAAM,GAAG,QAAQ,CAAC,cAAc,CAAC,QAAQ,CAAE,CAAC;AAElD,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE;IAClC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;AAChC,CAAC,CAAC,CAAA"
	}

view raw index.js.map hosted with ❤ by GitHub

When we render the webpage in the browser using a server (Live Server VSCode extension has been used here to server the index.html file in localhost), we see an error in the browser console, it contains the stack trace of the error. As we can see it is pointing at index.ts even though the browser in no way has access to our index.ts file or using it in any way.

If we check the browser Sources tab, we find we have both our Typescript and Javascript files.

Thus, from here we can also debug the code using our source Typescript code via the browser debugger. This may not seem to have a huge impact on debugging since the file transpiled here is very short. But eventually, for a larger and more complex project, it can ease a developer's job of debugging.

Conclusion:

Generating a source map for your transpiled/minified code allows you to simplify debugging and trace errors back to the original source. Incorporate source maps into your development workflow to enhance your debugging experience and streamline the error-tracing process.

Happy coding!