Using source maps with Sass 3.3

One of the exciting new features in Sass 3.3 that every developer should take advantage of is source maps.

As CSS pre-processors, minifiers, and JavaScript transpilers have become mainstream it is increasingly difficult to debug the code running in the browser because of differences with the original source code.

For example, if you use CoffeeScript (which compiles to JavaScript) you won't see CoffeeScript while debugging in the browser. Instead, you'll see compiled JavaScript. The same problem exists for Sass which compiles down to CSS.

Source maps seek to bridge the gap between higher-level languages like CoffeeScript and Sass and the lower-level languages they compile down to (JavaScript and CSS). Source maps allow you to see the original source (the CoffeeScript or Sass) instead of the compiled JavaScript or CSS while debugging.

In practice, for Sass users, this means that when you inspect an element with developer tools, rather than seeing the CSS styles associated with that element, you can see the code we really care about: the pre-compiled Sass.

Generating source maps for Sass

To get access to this feature in the browser, you need to generate a source map file for each source file.

For Sass, this is as easy as adding a flag to Sass's command line tool:

$ sass sass/screen.scss:stylesheets/screen.css --sourcemap

If you look in your output folder after running that command, you'll notice that a comment has been added to the end of the generated CSS file:

/*# sourceMappingURL=screen.css.map */

This points to an additional file that was created during compilation: screen.css.map, which - as the name implies - is what maps all of the compiled CSS back to the source Sass declarations. If you're interested in the details of this file and how source maps actually work, check out Ryan Seddon's Introduction to JavaScript Source Maps over at HTML5Rocks. (Even though the article implies that it's only about JavaScript, all source maps work the same.)

Enabling source maps in the browser

The second thing we need to do to take advantage of source maps is to make sure that our browser knows look for them. Chrome, Firefox and Safari all have support for source maps.

Chrome

If you're using Chrome, source maps are now part of the core feature set, so you don't have to monkey around in chrome://flags any more. Simply open up the DevTools settings and toggle the Enable CSS Source Maps option:

Firefox

For Firefox users, source maps are in version 29. You can enable them in the Toolbox Options menu (the gear icon) or by right-clicking anywhere in the Style Inspector's rule view and selecting the Show original sources option. (More info is available at the Mozilla blog.)

Safari

Safari is a bit ahead of the curve in terms of source map support. If a map file is detected, references are automatically changed to the source-mapped files, no configuration necessary.

Another tool in our belt

Once source maps are enabled in your browser of choice, the source reference for every style will change from the generated CSS to the source Sass, right down to the line number. Amazing!

Just as Firebug and its successors drastically improved our ability to debug in the browser, source maps increase the depth of our diagnostic capabilities. By allowing us to directly access our pre-compiled code, we can find and fix problems faster than ever. Now that I've been using source maps for a few months, I can't imagine working without them.