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!
Subscribe below and we’ll send you a weekly email summary of all new Web Design tutorials. Never miss out on learning about the next big thing.
Update me weeklyEnvato Tuts+ tutorials are translated into other languages by our community members—you can be involved too!
Translate this post