JavaScript Source Maps Guide

Compressing your JavaScript and CSS files is an old school trick to gain more speed for your website.

But what happens when you want to debug the code inside those auto-generated files? It can be a real headache to do so without using source maps.

Source maps are basically a mapping between each line in the compressed file to the corresponding line in the original source code. This way you can easily debug your application even if it runs with a compressed version of your code. Chrome and Firefox (23+) come with a built-in support for source maps.

What Are JavaScript Source Maps?

A source map is a JSON file, consists with all the information needed to map between each line in the compressed files back to the original source. The map file holds information about the mapping itself and the original uncompressed files.

Here’s an example of a source map JavaScript file (those files are generated automatically, but we still want to look inside them to understand them better)

{
    version: 3,
    file: "app.js.map",
    sources: [
        "module1.js",
        "module2.js"
    ],
    sourceRoot: "/",
    names: ["foo", "bar"],
    mappings: mapping code in Base64 VLQ format
}

version: the version number that the source map is based on (now, the source map revision is 3)
file: the source map file name
sources: an array of the original files names
sourceRoot: (optional) the root path for the files in the sources array to be resolved from
names: an array with all the variables and functions from the original source code (names only)
mappings: the mapping code in Base64 VLQ format

How to Generate JavaScript Source Maps

One of the common compressing tools available out there is UglifyJS2, it is a well known and tested plugin which can be used in many ways according to your build system. It can be used as a stand-alone tool or a plugin inside a separated optimization tool like WRO (recommended for every app).

According to UglifyJS2 documentation, source maps are supported and generated for the compressed files, you do need to append the necessary parameters to the command to tell it the output and root directories.

An example of how to generate a source map file (taken from the documentation)

uglifyjs /home/doe/work/foo/src/js/file1.js \
         /home/doe/work/foo/src/js/file2.js \
         -o foo.min.js \
         --source-map foo.min.js.map \
         --source-map-root http://foo.com/src \
         -p 5 -c -m

The above will compress file1.js and file2.js, will drop the output in foo.min.js and the source map in foo.min.js.map. The source mapping will refer to http://foo.com/src/js/file1.js and http://foo.com/src/js/file2.js (in fact it will list http://foo.com/src as the source map root, and the original files as js/file1.js and js/file2.js)

How to Use The Source Map File?

In order to tell the browser a source map file is available for the compressed file, the compressed file must indicate the source map URL at the end of it (UglifyJS2 does it for you).

Note: Chrome users should open developers tools (F12) -> go to settings -> make sure ‘enable javascript source maps’ is checked

Enable chrome source maps — Enabling chrome source maps from settings

When Chrome (or Firefox) see this line, they automatically download the source map and use the data inside it to show the developer the original uncompressed version of the source code. It’s important to know that this won’t affect people browsing your website, and won’t cause any performance issues because the source map is downloaded only in case the developer tools are open.

When you open chrome developers tools, first you need to refresh the page (the browser needs to load the map file). Then, you should be able to see the original uncompressed files like they are part of your resources, but if you examine your website source (CTRL+U), you should see that only the compressed file is referenced.

Check out this source map simple demo to see it in action.

Source map example — Show both minified and an uncompressed version of the script

More Resources

Conclusion

Source maps are definitely something every JavaScript developer must be familiar with.

Minifying and uglifying your resources is one of the easiest tricks to give your clients a better experience when they visit your website. Always think about your client, standing with his smartphone in his hand, waiting for your site to load. If it’s not going to load fast, this client will probably won’t wait.

My suggestion is not to wait until you really need those mapping and start checking about implementing them in your own environment. Major known libraries like browserify and google closure compiler support source maps. Other tools like SASS, LESS or even Babel, use source maps to enable developers debugging their code.

If you haven’t already compressed your resources, you should start now. And if you do compress your resources but don’t generated source maps for an easier debugging process, now it’s a good time.

Cheers

Contact Me