Skip to content

SourceMap

Why Do You Need SourceMap?

In the past, we built web applications using only HTML, CSS, and JavaScript, and deployed the same files to the network.

Since we are now building more complex web applications, your development workflow may involve using various tools. For example:

These tools require a build process to transpile your code into standard HTML, JavaScript, and CSS that browsers can understand. Additionally, to optimize performance, it is common practice to minify (e.g., using Terser to shrink and mangle JavaScript) and bundle these files, thereby reducing their size and improving web page efficiency.

For example, using a build tool, we can transpile and minify the following TypeScript file into a single line of JavaScript.

/* A TypeScript demo: example.ts */
document.querySelector('button')?.addEventListener('click', () => {
  const num: number = Math.floor(Math.random() * 101);
  const greet: string = 'Hello';
  (document.querySelector('p') as HTMLParagraphElement).innerText = `${greet}, you
  console.log(num);
});

The minified version looks like this:

/* A compressed JavaScript version of the TypeScript demo: example.min.js */
document.querySelector("button")?.addEventListener("click",(()=>{const e=Math.floor

However, this optimization makes debugging more difficult. If the minified code puts everything on one line and uses short variable names, it is hard to determine the root cause of an issue. This is where source maps come in – source maps map your compiled code back to the original code.

How to Generate SourceMap?

Source maps are files ending in .map (e.g., example.min.js.map and styles.css.map). Most build tools can generate source maps, such as Vite, webpack, Rollup, Parcel, esbuild, and others. Some tools include source maps by default, while others may require additional configuration to generate them.

/* Example configuration: vite.config.js */

/* https://vitejs.dev/config/ */

export default defineConfig({
  build: {
    sourcemap: true, // enable production source maps
  },
  css: {
    devSourcemap: true // enable CSS source maps during development
  }
})

Understanding SourceMap

These source map files contain important information about how the compiled code maps to the original code, making it easy for developers to debug. Below is an example of a source map:

{
  "mappings": "AAAAA,SAASC,cAAc,WAAWC, ...",
  "sources": ["src/script.ts"],
  "sourcesContent": ["document.querySelector('button')..."],
  "names": ["document","querySelector", ...],
  "version": 3,
  "file": "example.min.js.map"
}

The most critical element of a source map is the mappings field. It uses a VLQ base 64 encoded string to map lines and positions in the compiled file to the corresponding original file. You can visualize this mapping using source map visualization tools like source-map-visualization and source-map-visualization to verify file availability.

For example, a visualization of the code example generated by the visualization tool source-map-visualization:

The generated column on the left shows the minified content, and the original column shows the original source.

The visualization tool color-codes each line in the original column and the corresponding code in the generated column. The mappings section shows the decoded code mapping. For example, entry 65-> 2:2 indicates:

  • Generated code: The word const starts at position 65 in the minified content.
  • Original code: The word const starts at line 2, column 2 in the original content.

This allows developers to quickly determine the relationship between the minified code and the original code, making the debugging process smoother.

Browser developer tools apply these source maps to help you pinpoint debugging issues directly in the browser more quickly.

Feedback

Is this page helpful?