Source map support for web page debugging has been a thing now for a while. If you don't know what a sourcemap is, Ryan Seddon's article "Introduction to JavaScript Source Maps", provides a technical introduction. The "proposal" for source map seems to be here.
In a nutshell, sourcemap allow you to ship minized .js files (and maybe .css files), which point back to the original source, so that when you debug your code in a debugger like Chrome Dev Tools, you'll see the original source.
It's awesome.
Even better, we're starting to see folks ship source maps with their minized resources. For example, looking at the minized angular 1.2.0-rc.2 js file you can see the sourcemap annotation near the end:
/*
//@ sourceMappingURL=angular.min.js.map
*/
The contents of that .map file looks like this (I've truncated bits of it):
{
"version":3,
"file":"angular.min.js",
"lineCount":183,
"mappings":"A;;;;;aAKC,SAAQ,CAACA,CAAD,...",
"sources":["angular.js","MINERR_ASSET"],
"names":["window","document","undefined",...]
}
You don't need to understand any of this, but what it means is that
if you use the angular.min.js file in a web page, and also make
angular.min.js.map and angular.js files available, when you debug
with a sourcemap-enabled debugger (like Chrome Dev Tools), you'll see
the original source instead of the minized source.
But there are a few issues. Although I haven't written any tools to generate source maps, I do consume them in libraries and with tools that I use (like browserify). Sometimes I do a bit of surgery on them, to make them work a little better.
Armed with this experience, I figured I'd post a few "best practices", based on some of the issues I've seen, aimed at folks generating sourcemaps.
do not use a data-url with your sourceMappingURL annotation
Using a data url, which browserify does, ends up creating a huge single line for the sourceMappingURL annotation. Many text editors will choke on this, if you accidently, or purposely edit the file with the annotation.
In addition, using a data-url means the mapping data is uuencoded, which means humans can't read it. The sourcemap data is actually sometimes interesting to look at, for instance, if you want to see what files got bundled with browserify.
Also, including the sourcemap as a data-url means you just made your "production" file bigger, especially since it's uuencoded.
Instead of using a data-url with the sourcemap information inlined, just provide a map file like angular does (described above).
put the sourceMappingURL annotation on a line by itself at the end
In the angular example above, the sourceMappingURL annotation is in a // style
comment inside a /* */ style comment. Kinda pointless. But worse,
it no longer works with Chrome 31.0.1650.8 beta.
Presumably, Chrome Dev Tools got a bit stricter with how they recognize the sourceMappingURL annotation; it seems to like having the comment at the very end of the file. See https://code.google.com/p/chromium/issues/detail?id=305284 for more info.
Browserify also has an issue here, as it adds a line with a single semi-colon to the end of the file, right before the sourceMappingURL annotation, which also does not work in the version of Chrome I referenced.
name your sourcemap file <min-file>.map.json
Turns out these sourcemap files are json. But no one uses a .json file extension, which seems unfortunate as the browser doesn't understand them, if you happen to try loading one of the files there. Not sure if there's a restriction about naming them, but it seems like there shouldn't be, and it seems like it makes sense to just use a .json extension for them.
embed the original source in the sourcemap file
Source map files contain a list of the names of the original source files
(urls, actually), and can optionally contain the original source file content
in the sourcesContent key.
Not everyone does this - I think most people do not put the original source
in the sourcemap files (eg, jquery, angular).
If you don't include the source with the sourcesContent key, then the source
will need to be retrieved by your browser. Not only is this another HTTP GET
required, but you will need to provide the original .js files as well as the
minized .js files on your server. And they will need to be arranged in whatever
manner the source files are specified in the source map file (remember, the
names are actually URLs).
If you're going to provide a separate map file, then you might as well add the source to it, so the whole wad is available in one file.
generate your sourcemap json file so that it's readable
I'm looking at you, http://code.jquery.com/jquery-2.0.3.min.map.
The file is only used at debug time, it's unlikely there's going to be much of a performance/memory hit by single-lining the file. Remember, as I said above, it's often useful to be able to read the sourcemap file, so ... make it readable.
if you use the names key in your sourcemap, put it at the end of the map file
Again, sourcemap files are interesting reading sometimes, but the names key
ends up being painful to deal with, if you generate the sourcemap with
something like JSON.stringify(mapObject, null, 4) or something. Because
the value of the names key is an array of strings, and it's pretty long,
as is not nearly as interesting to read as the other bits in the source map.
Add the property to your map object last, before you stringify it, so it
doesn't get in the way.
where can we publish some sourcemap best practices?
I'd like to see somewhere we can publish and debate sourcemap best practices. Idears?
bugs opened
Some bugs relevant to the "sourceMappingURL not the last thing in the file" issue/violation: