How to Use Source Maps for Better Preprocessor Debugging

CSS preprocessors have become an indispensable tool for most front-end developers. However, despite the many advantages they provide, using tools like LESS, Stylus or Sass also present new problems, one of which we’re going to talk about (and solve) in this tutorial.

The Problem

Unless you’re working on a small website with very few pages, it’s a common best practice to divide the stylesheet into several modules, or partials. For example, we could separate the styles for navigation into their own partial named navbar.scss (the preprocessor here being Sass). Then we import this, along with other partials, into a single primary stylesheet using the @import directive after which they will be compiled into a single CSS file. This is where the problem begins.

Browsers parse the compiled CSS, not your work files, which ultimately makes style debugging more tricky. The debugging process can be really cumbersome if you are handling a large scale project with dozens of stylesheets to manage. Figuring out where compiled styles originated can be almost impossible.

As you can see below, the web inspector refers to the .css file, telling us that the style for the body is declared on line 270. That doesn’t help us much, because in our work files it is actually declared in scaffolding.less on line 27.

The Source Map Solution

Using a source map will bridge these communal style languages. Source maps are separately generated files which allow browsers to trace the compiled CSS back to its original source. In actual fact, source maps can be used in many coding environments:

“Source maps offer a language-agnostic way of mapping production code to the original code that was authored.” - Sayanee Basu

For our purposes, source maps make style debugging with a CSS preprocessor as familiar as working with plain CSS. As you can see below, the web inspector is now showing the style reference to the original source, thanks to the source map.

Generating a Source Map

To get started, we first need to generate a source map file (.map) along with the generated CSS. This .map file contains JSON formatted code to serve as a reference between the compiled file and the original source. Sass added the support for generating source maps in version 3.3, LESS added it in version 1.5.0 and you can also find information about Stylus support of source maps in the documentation.

Everyone has their own preference when it comes to picking up the tools that fit within their workflow. Aside from the native Command Line Interface (CLI) which each CSS preprocessors provides, we also have a few other options like Grunt and Gulp, even applications like Codekit.

Using the CLI

All the main preprocessors have the ability to create a source map through their CLI. 

LESS

With LESS, you could include --source-map flag this way:

lessc styles.less > styles.css --source-map=styles.css.map

This example compiles styles.less into styles.css, whilst at the same time generating the source map file with the name set to “styles.css.map”.

Sass

Sass users can use the --sourcemap (without the hyphen) to do the same, for example:

sass styles.scss:styles.css --sourcemap

Unlike LESS, the --sourcemap flag in Sass does need us to specify the file name. Sass will name the file with the same name as the compiled style sheet by default. So, given the above example the source map name would still be “styles.css.map”.

Stylus

Just like Sass, Stylus only requires the --sourcemap flag, or additionally offers the shorthand -m:

stylus -m styles.styl

Again, this gives us “styles.css.map”.

Using a Task Runner

If you prefer using a task runner like Grunt, use grunt-contrib-less, grunt-contrib-sass or grunt-contrib-stylus to compile the CSS, then include the option to generate the source map. The example below effectively does the same as we did in the previous example; it generates a source map named “styles.css.map” from our styles.less file.

module.exports = function(grunt) {
  grunt.initConfig({
    less: {
      options: {
            sourceMap: true,
            sourceMapFilename: styles.css.map
      },
      files: {
            'styles.css': 'styles.less'
      }
    }
  });
  grunt.loadNpmTasks('grunt-contrib-less');
  grunt.registerTask('default', ['less']);
};

Sass users can use grunt-contrib-sass and set the option in the same fashion, for example:

module.exports = function(grunt) {
  grunt.initConfig({
    sass: {
      options: {
        sourcemap: 'auto'
      },
      files: {
        'styles.css': 'styles.scss'
      }
    }
  });
  grunt.loadNpmTasks('grunt-contrib-sass');
  grunt.registerTask('default', ['sass']);
};

Using an Application Interface

The easiest way, particularly if you are not that comfortable with the command line, is by using a graphical interface like Codekit, Prepros or Koala. With the application, creating a Source Map is as straightforward as a single click.

Once the source map is successfully created, you will find a new file .map as well the reference pointing to the source map file at the bottom of the compiled stylesheet. This reference comment will typically look a bit like:

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

Source Map Support in Browsers

All the latest browsers support source maps. Safari will activate itself once the source map file is available, without the need for configuration. In the other browsers such Firefox, Chrome and Opera, source maps may be turned off by default in which case you’ll need to toggle the settings.

Firefox

In Firefox, source map inspection is only available through the Firefox built-in DevTools. Firebug — the once popular debugging add-on for Firefox — hasn’t yet added this feature, unfortunately. Therefore, launch the Firefox DevTools and enable source maps by right-clicking on any style reference and selecting the “Show original sources” from the context menu.

Chrome

In Chrome (as well as Opera 12 and upwards) click the “gear” icon in the web inspector and make sure that Enable CSS source maps is checked.

Once the source map file is created and the feature in the browser is enabled, you should find the inspector pointing to the original source. In this case, the you can see the inspector directly referencing scaffolding.less.

Wrapping Up

Now, with the power of source maps at your finger tips, you’ll be able to debug compiled styles just as web designers have been doing with CSS for years. So, don’t forget to generate a source map for your next compiled stylesheet!