Site icon Treehouse Blog

An Introduction to Source Maps

One of the easiest performance wins you can gain for your website is to combine and compress your JavaScript and CSS files. But what happens when you need to debug the code within those compressed files? It can be a nightmare. Fear not however, there is a solution on the horizon and it goes by the name of source maps.

A source map provides a way of mapping code within a compressed file back to it’s original position in a source file. This means that – with the help of a bit of software – you can easily debug your applications even after your assets have been optimized. The Chrome and Firefox developer tools both ship with built-in support for source maps.

In this blog post you’re going to learn how source maps work and take a look at how to generate them. We’re going to be focussing primarily on source maps for JavaScript code but the principles apply to CSS source maps too.

Note: Support for source maps is enabled by default in Firefox’s developer tools. You may need to enable support manually in Chrome. To do this, launch the Chrome dev tools and open the Settings pane (cog in the bottom right corner). In the General tab make sure that Enable JS source maps and Enable CSS source maps are both ticked.

How Source Maps Work

As the name suggests, a source map consists of a whole bunch of information that can be used to map the code within a compressed file back to it’s original source. You can specify a different source map for each of your compressed files.

You indicate to the browser that a source map is available by adding a special comment to the bottom of your optimised file.

//# sourceMappingURL=/path/to/

This comment will usually be added by the program that was used to generate the source map. The developer tools will only load this file if support for source maps is enabled and the developer tools are open.

You can also specify a source map is available by sending the X-SourceMap HTTP header in the response for the compressed JavaScript file.

X-SourceMap: /path/to/

The source map file contains a JSON object with information about the map itself and the original JavaScript files. Here is a simple example:

    version: 3,
    file: "",
    sources: [
    sourceRoot: "/",
    names: ["slideUp", "slideDown", "save"],
    mappings: "AAA0B,kBAAhBA,QAAOC,SACjBD,OAAOC,OAAO..."

Lets take a closer look at each of these properties.

Are you ready to start learning?

Learning with Treehouse for only 30 minutes a day can teach you the skills needed to land the job that you’ve been dreaming about.

Start a Free Trial

Generating Source Maps with UglifyJS

UglifyJS is a popular command line utility that allows you to combine and compress JavaScript files. Version 2 supports a number of command line flags that help with generating source maps.

Here’s an example command that uses some of these command line flags.

uglifyjs [input files] -o script.min.js --source-map --source-map-root -c -m

Note: If you use the grunt-contrib-uglify plugin for Grunt, refer to the documentation for information on how to specify these options in your Gruntfile.

There are also a number of other utilities available that have support for generating source maps. A selection of these are listed below.

Source Maps in Chrome Dev Tools

The Sources Tab in Chrome Dev Tools

If you have your source maps set up correctly, you should see each of the original JavaScript files listed in the file pane of the Sources tab.

Examining the HTML for your page will confirm that only the compressed JavaScript file is being referenced. The dev tools is loading the source map file for you and then fetching each of the original source files.

Try a Demo

Source Maps in the Firefox Developer Tools

The Debugger Tab in the Firefox Developer Tools

Firefox users can see the individual source files in the Debugger tab of the developer tools. Again the dev tools has identified that a source map is available and has then fetched each of the referenced source files.

Should you wish to view the compressed versions instead, click the cog icon in the top right corner of the tab and deselect Show original sources.

Try a Demo

Final Thoughts

Using source maps allows developers to maintain a straight-forward debugging environment while at the same time optimizing their sites for performance.

In this post you have learned how source maps work and seen how you can generate them using UglifyJS. If you ever ship websites with compressed assets (which you should), it’s really worth taking the time to integrate source map creation into your workflow.

Useful Links

Exit mobile version