Using Source Maps

When CoffeeScript was first released in 2009, source maps were but a twinkle in some Google engineers’ eyes. The problem of debugging obfuscated JavaScript has existed ever since the dawn of web development, thanks to minification. Google decided to try to tackle the problem in their minification tool, Closure Compiler, by creating metadata called source maps that their Closure Inspector tool could parse. This metadata allowed pieces of minified code to be mapped to the original source code during debugging. In 2011, Google moved to add source maps to the debugging tools in WebKit, the engine underlying Safari and Chrome. (Google would later fork WebKit into a new engine called Blink.) Mozilla and Microsoft followed their lead. Today, all major browsers support the source map spec.

With source maps, compiled JavaScript can be delivered to the browser just as it would be otherwise: compiled, concatenated, and minified for maximum efficiency. The only overhead is a single comment (called the “pragma”) containing the path (relative or absolute) of the script’s corresponding source map, which conventionally has the same name as the script with the addition of the file extension map:

The comment is ignored when an ordinary user visits the page. But if you pop open the developer tools, the browser will try to load that map file. The map file, in turn, will tell the browser where it can find the original source file (or files) that were compiled into the script. Once the browser has downloaded all of those files, the developer tools will be able to provide much richer debugging information.

In the context of CoffeeScript, source maps mean that the longstanding dream of debugging CoffeeScript code in the browser—seeing the line of CoffeeScript code from which an error was thrown rather than seeing only the compiled JavaScript—can finally be realized. The development language and the production language are finally one and the same, provided that you’ve set up a build and deployment pipeline that generates the proper source maps and makes them available to the browser.

In later chapters, we’ll use Grunt to generate source maps alongside our compiled JavaScript and ensure that those files end up where they need to be. We’ll also see how source map debugging can be added to Node.js for server-side applications written in CoffeeScript. If you want to give source maps a whirl right now, just run the compiler with the -m (shorthand for --map) flag:

A note for Rails users: as of this writing, Sprockets (the Rails asset pipeline) does not support source maps. But don’t be discouraged! Source map support is a top priority for the next major release, Sprockets 4.0.^[23] I’m excited about this because it should make source maps “just work” in Rails, all the way from development to production. In the meantime, a plugin is available to generate CoffeeScript source maps in development mode.^[24]