Jecelyn Yeen

Source maps are a crucial tool in modern web development that make debuggingsignificantly easier. This page explores the basics of source maps, how they'regenerated, and how they improve the debugging experience.

The need for source maps

Early web apps were built with low complexity. Developers deployed HTML, CSS,and JavaScript files directly to the web.

More modern and complex web apps can need a variety of tools in theirdevelopment workflow. For example:

• Templating languages and HTML preprocessors:Pug,Nunjucks,Markdown.
• CSS preprocessors:SCSS,LESS,PostCSS.
• JavaScript frameworks:Angular,React,Vue,Svelte.
• JavaScript meta frameworks:Next.js,Nuxt,Astro.
• High-level programming languages:TypeScript,Dart,CoffeeScript.

These tools require a build process to transpile your code into standard HTML,JavaScript, and CSS that browsers can understand. It's also common practice tooptimize performance by minifying and combining these files, using a tool likeTerser.

For example, using build tools, we can transpile and compress the followingTypeScript file into a single line of JavaScript. You can try it for yourself inthisdemo on GitHub.

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

A compressed version would be:

/* A compressed JavaScript version of the TypeScript demo: example.min.js  */document.querySelector("button")?.addEventListener("click",(()=>{conste=Math.floor(101*Math.random());document.querySelector("p").innerText=`Hello, you are no.${e}!`,console.log(e)}));

However, compressing your code can make debugging more difficult. Source mapscan remove this problem: by mapping your compiled code back to the original code,they can help you quickly find the source of an error.

Generate source maps

Source maps are files whose names end with.map (for example,example.min.js.map andstyles.css.map). They can be generated by most buildtools, includingVite,webpack,Rollup,Parcel, andesbuild.

Some tools include source maps by default. Others might need additionalconfiguration to produce them:

/* Example configuration: vite.config.js *//* https://vitejs.dev/config/ */exportdefaultdefineConfig({build:{sourcemap:true,// enable production source maps},css:{devSourcemap:true// enable CSS source maps during development}})

Understand the source map

To help with debugging, these source map files contain essential informationabout how the compiled code maps to the original code. Here's an example of asource map:

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

To understand each of these fields, you can read thesource map specification orThe anatomy of a source map.

The most important part of a source map is themappings field. It uses aVLQ base 64 encoded stringto map lines and locations in the compiled file to the corresponding originalfile. You can view this mapping using a source map visualizer likesource-map-visualization orSource Map Visualization.

Thegenerated column on the left shows the compressed content, and theoriginal column shows the original source.

The visualizer color-codes each line in theoriginal column with itscorresponding code in thegenerated column.

Themappings section shows decoded mappings of the code. For example, theentry65 -> 2:2 means:

• Generated code: The wordconst starts at position 65 in the compressed content.
• Original code: The wordconst starts at line 2 and column 2 in the original content.

This lets developers quickly identify the relationship between the minified codeand the original code, making debugging a smoother process.

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

Source map extensions

Source maps support custom extension fields that start with anx_ prefix. Oneexample is thex_google_ignoreList extension field proposed by ChromeDevTools. Seex_google_ignoreListto learn more about how these extensions help you focus on your code.

Source map drawbacks

Unfortunately, source mappings aren't always as complete as you need them to be.In our first example, the variablegreet was optimized away during the buildprocess, even though its value is directly embedded into the final string output.

In this case, when you debug the code, developer tools might not be able toinfer and display the actual value. This kind of error can make your codemonitoring and analysis harder.

This is a problem that needs to be solved within the design of source maps. Onepotential solution is to include scope information in the source maps in thesame way other programming languages do with their debug information.

However, this requires the whole ecosystem to work together to improve thesource map specification and implementation. To follow the ongoing onimproving debuggability with source maps, refer to the proposal forSource Maps v4on GitHub.