Web Development➝Source maps for private code

If you're doing front end web development these days, chances are the source code you write is being transformed in your build process before it reaches the browser. It might be minification, transpilation or possibly compilation from a completely different language.

At some point, inevitably, you're going to want to debug the generated code that the browser is running, and it might be so terribly obfuscated from the code you wrote that it's impossible to work out exactly what is going on.

The solution is to use source maps. They essentially provide an inverse lookup from positions in your generated code back to your original source code. Source maps can be created during your build, and most build processes have some form of source map support these days.

In order to use a source map, your browser dev tools need first to be able to find it. If your generated code is JavaScript, one way to let the dev tools know where to look is to add a comment to the end of the generated code which defines the sourceMappingURL - the location of the source map.

//# sourceMappingURL=mylib.js.map

If this URL is not absolute, then it is assumed relative to the location of the generated code.

Now when you open your browser dev tools to debug the generated code, the tools can download the source map and use it to map back to your original source code.

There are a couple of ways the source map can link back to the original sources. One possibility is to have your source code available at some URL and have the source map point at that via it's sourcesRoot property. However the option I'd recommend is creating your source maps with the original source code embedded inside them using the sourcesContent property. For one it means you don't have to host your source code. But further, if you change your source code without rebuilding, your source map is still going to work as it contains a snapshot of the source code from the time of the build.

So you now have working source maps allowing you to debug your generated code. But, if you've distributed your source maps along with your generated code, so can everyone else! You may not want this, after all not all code is open source. So how do you debug your generated code without distributing the source maps?

One way to solve this is to host your source maps on a private website. This may be on localhost, or possibly shared on your private network. Let's say you set up a private site http://sourcemaps/, then the source mapping URL in your generated code can be set up to point at this site.

//# sourceMappingURL=http://sourcemaps/mylib.js.map

This way anyone who opens up the browser dev tools without having access to your (or their own equivalent) sourcemaps site will not be able to load the source maps (it'll 404 in the dev tools) and so your original source code is safe from prying eyes. You, however, will be able to debug your generated code with the aid of the correct source maps.

If writing a private URL into your generated code feels like a hack to you, then I agree. I would much rather the browser dev tools implemented a feature allowing you to choose root locations to use when resolving non-absolute source mapping URLs. A lot like how when debugging dlls in Visual Studio you can choose a symbols server to point at to look for the relevant pdb files. Imagine something like this: