Faster Sass debugging and style iteration with source maps, Chrome Web Developer Tools and Grunt

| 47 replies | Short URL:

This is the third re-write of this post since first posting it back in November 2012. I’ll keep trying to update as and when things change as there’s every chance you are visiting this from a link in the book ‘Sass and Compass for Designers’.

Minor update 27 May 2014: For those looking for Compass compatibility with source maps, that fine fellow Dennis Gaebel has put together a small project on GitHub providing demo configurations for Compass based source maps (there are branches for Grunt, Gulp, CodeKit 2). Take a look at the various files here:

Main copy:

Safari 6.1+ and the latest versions of Chrome (use v29+ of Chrome, if your ‘stable’ version isn’t yet at v29, grab the ‘Beta’ or ‘Dev’ version here: use ‘source maps’ for Sass debugging. In order to get this working with Sass, you’ll need Sass 3.3 (pre-release at the time of writing). To get the pre-release version of Sass run sudo gem install sass –pre in the CLI. Then run sass -v to check.

There are now plenty of other resources on the Net to explain how to get this up and running from the command line using the Sass watch command. There’s a good one over at Net Tuts: I’ve therefore omitted that section from this rewrite. Why I hear you (one person if I’m lucky) cry?

Well, I think there is a simpler way to source mapping glory by using Grunt to compile your Sass. And how about automatic live reloading of changes in the browser to boot? If you know nothing of Grunt, fear not, it’s perhaps a topic for another day. All you need (hopefully) is to follow along and do a little cut and paste.

Grunt users, you’ll know which bits to skip, for everyone else, crack open your text editor of choice and your Terminal (sorry Windows users).

  1. Go download and install Node. It’s a clicky-clicky install. No command-line nerdery needed. Done? Excellent…
  2. In the root of your project make two blank files. One called ‘package.json’ and the other called ‘Gruntfile.js’
  3. Copy and paste this into the package.json file:

  "name": "YOUR PROJECT NAME",
    "version": "0.0.1",
    "devDependencies": {
        "grunt": "~0.4.5",
        "grunt-contrib-watch": "~0.6.1",
        "grunt-contrib-sass": "~0.7.3"
  1. Copy and paste this into the Gruntfile.js file:

module.exports = function(grunt) {
        pkg: grunt.file.readJSON('package.json'),
        watch: {
            sass: {
                files: ['sass/**/*.{scss,sass}','sass/_partials/**/*.{scss,sass}'],
                tasks: ['sass:dist']
            livereload: {
                files: ['*.html', '*.php', 'js/**/*.{js,json}', 'css/*.css','img/**/*.{png,jpg,jpeg,gif,webp,svg}'],
                options: {
                    livereload: true
        sass: {
            dist: {
                files: {
                    'css/styles.css': 'sass/styles.scss'
                options: {
                    sourcemap: 'true'
    grunt.registerTask('default', ['watch']);
if you have no idea what this is don’t worry for now. However, the important points are that in this case all my Sass files are living in a folder called ‘sass’ in the root of the project (at the same level the Gruntfile.js and package.json are) and the resultant CSS is being compiled into a folder called ‘css’ also in the root of the project folder. If your folders and paths differ, amend the below to suit.
  1. Let’s install Grunt. From the command line run this command (you may need to prefix it with ‘sudo’): npm install -g grunt-cli. This installs the Grunt command ‘globally’ so you can run it from any locationl

  2. Now, if you aren’t already in the root of your folder, move there e.g. cd ~/Sites/MY PROJECT. Now run (again you may need to add sudo to the beginning if you see a bunch of errors) npm install. Once that’s finished, if you look in the root of your folder you should see a ‘node_modules’ folder. Just ignore that, you don’t need to touch it.

  3. Now, from the command line and still within your project folder run ‘grunt’ (e.g. newbie tip: just type grunt and press enter) and you’ll see something like this on the command line:

Running "sass:dist" (sass) task

Running "watch" task

Now, to actually see the Source Map support in Chrome (it shows regardless in Safari 6.1+):

  1. Type ‘chrome://flags’ in the Chrome address bar and switch on ‘Enable Developer Tools experiments’. Restart Chrome. [note: in recent versions of Chrome e.g. 30+ you won’t need to do this step]
  1. Now back in Developer Tools, click on settings (cog icon in the bottom right), click the experiments tab and then tick the ‘Support for Sass’ tick box. [note: in recent versions of Chrome e.g. 30+ you won’t need to do this step]

Now in the General tab of Web Developer Tools settings, under the ‘sources’ header, ensure ‘enable CSS source maps’ is ticked (note: it used to have a single button for both CSS and JS source maps as shown in the image. Now there are separate ones). Also tick the ‘Auto-reload generated CSS’.

  1. If you don’t already have the Chrome LiveReload extension you’ll want to install that and click the icon to get some automatic LiveReload of changes. You’ll want the same extension if you work with Safari.

Now back to Sass:

Re-save your styles.scss file and you should see the CSS compiled and Sass/Grunt will also generate a file called It looks like utter gibberish but Chrome knows what to do with it. When you open Chrome and inspect the styles of your project not only will you be able to see the partial file that originated the style, you’ll also be able to click it’s name to be taken straight to the file in the dev tools.


Jumping to particular partial or particular property/value

Debugging with source maps works beautifully, even better than the previous debug info. As an example of the additional hotness, you can not only click the partial name/no (e.g. _layout:4) in the elements panel to go straight to that name. If you command-click one of the property names within the selector (e.g. color) it will take you directly to the line in the Sass that colour is declared.

Saving back to the Sass file from within Dev Tools

Further more, you can even set up Chrome to write back to the source Sass files (something that right now I’m not sure you can do with Safari) with changes you make to styles in the Dev tools. To do that, within the sources panel, right-click your file and choose ‘save-as’. Browse to the location of the Sass partials.


Now, when you edit a file in the Sass tools not only do you see instant changes, you can also click command+S to save those files back the partial – no more double-punching buttons!

You can go one step further and add a ‘mapping’. This then gives Chrome access to your file system without needing to ‘save as’ to a file each time. The idea is to create a 1:1 parity between the files that Chrome is rendering on the screen and the source files you are using to generate things. Let’s set this up.

First of all you need to set the mapping up. With Dev Tools open click the little cog down the bottom right to enter settings:


Now click ‘Workspaces’ on the left and ‘Add folder’ button on the right.


Browse to the relevant place your source files are saved on your machine (e.g. ~/Sites/MY SITE NAME). On choosing you will see a yellow warning prompt from Chrome asking you to confirm that you give it access. Click allow.

You’ll now see the file path in the Folders window of ‘Workspace’:


Close the setting screen down and click the ‘Sources’ tab of Dev Tools. Now pay attention because this is the bit that can easily trip you (read: me) up. Right-click one of the partials in the SERVER side of things. To be clear, if you are using some localhost of sorts, it will be ‘localhost:8888’ or similar – generally listed before the local file system (indicated in my grab by the folder ‘bf2013’ at the bottom), with a partial selected, choose ‘Map to File System Resource…’


You’ll see a pop-up box asking you to choose the relevant file. In this example, the equivalent file on my local system is the fourth one down (e.g. not the .sass-cache ones) so that’s the one to select.


With that done, Chrome will advise it needs to restart Dev Tools. Allow it to do so.

Now, when you click on a partial name in Dev Tools, or command-click a property/value and it takes you to the partial within Dev Tools, you can edit a property/value/whatever and click ‘command+s’ and the change will be saved back to the source files.


Amazing – no more round trips to the text editor.


With that and this little Grunt set-up Grunt (should) now automatically watch for changes in any of your project files you make in your text editor and update the browser accordingly, producing a new source map file each time for easier debugging. Chrome on the other hand will handle changes happening from the other direction, saving any changes there back to the source files. Admittedly, it’s a bit of a chore to set up but its sweet when done!

PS. Grunt and the associated plugins are amazing. A big thanks to everyone involved in those projects and for the Chrome team for making such great tools to work with. Kudos.

About The Author

47 Responses to “Faster Sass debugging and style iteration with source maps, Chrome Web Developer Tools and Grunt”

  1. Henry Blyth

    Brilliant, thanks for the detailed steps!

    On a side note, your next- and previous-post links could be written differently so you don’t get multiple colons in one sentence if your post title has a colon =)

  2. Roman

    Thanks for sharing this, it looks really promising. But for some reason I can’t make it work. I’m following all the steps correctly, I think, but all my CSS rules appear as if they were index.html on some random line, even non-existent lines…
    Any idea about what might be wrong? I would really appreciate it!

  3. Ben Frain

    Hi Roman, off-hand I don’t but if you want to upload (or email me at contact at benfrain dot com) a screengrab of your dev tools window somewhere (just right click on an element and choose ‘inspect element’) that might provide the answer.

  4. Roman

    Hey! Thank you for the fast reply. I sent you a screenshot, but it might not be of much help…

  5. Ben Frain

    Roman, if you look in your compiled CSS, are you getting lines like this:

    @media -sass-debug-info{filename{font-family:file\:\/\/\/Users\/benfrain\/Documents\/Storage\/articles\/code\/sass\/partials\/_modules\.scss}line{font-family:\00003175}}


  6. Roman

    Yes. They look like this:
    @media -sass-debug-info{filename{font-family:file\:\/\/D\:\/XAMPP\/htdocs\/manodeagua\/static\/sass\/_normalize\.scss}line{font-family:000331}}

  7. Ben Frain

    Hi Roman, Mmmm, weird. Afraid I don’t have the answer. I’m on Mac, looks like you are on Windows – shouldn’t be any disparity but don’t have a win box here to check. My next idea would be to re-run through all the steps above.

    If still not working I would create a very simple HTML doc with a single SCSS file linked and inspect that (just to check there is no weirdness in your current project).

    When you figure it out, would you mind posting back? I can update the post if need be and it will help any others that encounter the issue.

  8. Roman

    OK, I checked it with a new project and it worked. But I can’t figure out what is wrong with the other one. If I do I’ll let you know.

  9. Sheldon Kreger

    I turned these settings on. However, once I was ready to push my code off of my development server, I wanted to remove the CSS comments. So, I reset all of the variables and saved my config.rb, thinking this would do it. However, the comment code was still being added to my CSS files.

    The trick is to run “compass clean” after turning off the debugging variables. Then the CSS will be comment free and ready for deployment :-)

  10. Juan

    Not working for me… I tried both on Canary 27.0.1438.3 and Chrome 27.0.1430.3 dev-m. I’m using Sublime Text 2 and Compass.

    I’m getting lines in my css like this:
    @media -sass-debug-info{filename{font-family:file\:\/\/C\:\/Users\/Juan\/Desktop\/style\.scss}line{font-family:00031}}

    Can anyone help me?? :(

  11. Ben Frain

    Hi Juan, weird. Do you definitely have something like this in your config.rb sass_options = {:debug_info => true}? Mine is working as of 26.0.1410.12 dev.

  12. Ben Frain

    Juan, think it’s a Chrome thing. Just updated to 27.0.1438.7 dev and it’s no longer working for me. Seems to go off and on with updates so perhaps the next update will bring it back.

  13. hannes

    Thanks for the update! Took me some time to figure out why all the old how-to’s didn’t work anymore |-(

  14. Dennis Gaebel

    One day this will be easier to turn on and hit the ground running. Still early in its develoment to trust and doesn’t always produce expected results. Basically watch out for dragons at this time and don’t be surprised if source maps don’t behave at your party.

  15. Daniel Golden

    Your compiling via Sass. Is this possible to do when compiling via Compass?

  16. Ben Frain

    Not easily at present. If you look at the github link in the ‘Useful links’ section of the post you can see the current state of play.

  17. Ben Frain

    Hi Katja,

    Yes, I’m finding it flakey myself at present so I’ve given up trying to use it for the time being. It’s fine with just Sass but using Compass as well it’s tricky. I believe Paul Irish (Google Web Deb/Web Dev Genius) will be writing up some notes on it soon so it’s probably worth looking back at the GitHub link every few days to see what’s changed.

  18. Chip Cullen

    Just wanted to point out that the very current (as of today, June 12th, 2013) SASS 3.3.0 alpha seems to break Compass 0.12.2. I was tripped up by running

    sudo gem install sass –pre

    Because it installed Alphia 184. As I mentioned, trying to compile with this breaks Compass 0.12.2.

    I had to run

    sudo gem install sass –version 3.3.0.alpha.141

    To specifically install alpha 141, and the rest of the directions worked great.

  19. Dan

    Great … seams to be a bug in 184 even when using Sass without Compass. Using alpha 141 makes soucemaps work again.

  20. Ben Frain

    Thanks Dan. I’ll be having another look at this this week so will update accordingly.

  21. Jess Telford

    It should be noted that as of Chrome v28, Sass Sourcemap support is baked in (so you no longer need to use Canary / Chromium Nightlies).

  22. Shay

    Great article Ben (as usual) , and thanks for the updates too :)

    Spotted a small typo “The latest versions of Chrome use ‘source maps’ for Sass debgging.” – missing a “u” in “debugging”.

  23. Tri Nguyen

    I just tried this out and it works beautifully on Chrome Canary. However my Chrome 28.0 isn’t showing the .scss files at all and is still pointing to the compiled .css.

  24. Tri Nguyen

    Hey Ben,

    I just downloaded and used the Dev release of Chrome for Mac that you sent and confirmed that it DOES work on this version.

    I read somewhere someone claimed that sourcemap works with Chrome 28.0, but I guess that isn’t completely true.

  25. Chris

    I almost committed suicide after getting lost down a scary @ss hole of ruby and gem cmd line nightmares … but finally got this working. Getting this working is crucial to SASS adoption for me because I can’t live w/out the CSS-DevTools workflow magic. Thanks for this post!

    Things I had to do:
    – Uninstall sass ($gem uninstall sass)
    – Install RubyInstaller DevKit
    – Add my C:\Ruby path to the config.yml (from DevKit’s $ruby dk.rb init)
    – Run $ruby dk.rb install
    – Install bleeding edge sass ($gem install sass –pre)
    – Make sure my gruntfile.js had proper css:scss paths in the files section

    After the above and other stuff and praying/headdesking 33 times I got it working.

    Thanks again.

  26. Ben Frain

    Chris, thanks. That made me chuckle. I’ve never set it up on a Windows box and your frustration at getting through it came through loud and clear.

    Appreciate you detailing the pointers though in case anyone else comes up against them. Sorry I led you into hair pulling but glad you got through the other side ;)

  27. Morten Kirstein

    Hey Ben.

    I was trying to follow your steps in letting Grunt handle the Source mapping.

    But when i try to do the “npm install” command im getting an error.
    Im currently in the working directory.

    my first error is “npm ERR! install Couldn’t read dependencies”
    followed by a few other.

    I´ve been trying on 2 different Mac´s but same result. :(

    Do you have any idea of what i maybe doing wrong?

    Second. thx for the great performance @ CSS Summit 2013 :)

  28. Ben Frain

    Hi Morten,

    OK, obvious stuff first. Have you definitely done the clicky install?

    Have you also followed the install instructions through?

    Let me know and we can hopefully figure it out from there.

    Thanks Ben

  29. Benjamin Knight

    As of Chrome 30 there is no “Support for Sass” option in the Experiments tab of the dev tool settings.

    Using source maps with preprocessors is documented here:

    Unfortunately this means if you’re using a CSS preprocessor that isn’t Ruby 3.3.0 (currently alpha), you still have -sass-debug-info lines, and you may want to consider using Firefox if you really want to use source maps.

  30. John

    Hi Ben,

    Well found this article, and was hoping it would resolve the issue with Canary, but no luck. Issue being having to manually update the the sass files every time I make a change within dev tools

    I am old school (although some may so not so educated school or adverse with the more advanced tools of web development) and all this cmd line crap does my head in, seriously, really frustrates the hell out of me …

    Saying all that ,some months ago I eventually got going with Yeoman (and obviously that included grunt so was hoping after seeing your article I was half way there) …

    All I need is to get dev tools updating my sass files and I will be a very happy man … that will do me.

    I woke up this morning to finish of a project (a Sunday morning I ask you), and well 4 hours later I haven’t done a thing but try and get Canary to allow me to set source map support. (Version 32.0.1690.2 canary Aura)

    I have updated every Gem (don’t know why ,some article said so)
    I have updated Ruby Dev tools took me hours to get the path pointing correctly, and still not sure if that’s done correctly
    I have reinstalled Grunt, once again this didn’t make sense but an article said so
    All in-all I think I have managed to distort my install of Yeoman but was willing to live with that if I could get going with source map support

    (Contrary to the above few lines, I wouldn’t jump into a river if someone told me too!)

    And after all that, I can’t even update to a beta version of sass, currently running 3.2.12 and well see I need at least 3.3 to get this working with Canary (feast your eyes on this error report from within ruby cmd )

    Seriously, really genuinely, life seemed so much more relaxing when I had my scout app and my scout app alone … I had little expectation there, it did what it did, compiled my SASS and I knew I had to update from within my IDE, it may have took me longer but God did it work with little or no frustration or hope.

    I just wish there was a straight forward way to update the .scss files within dev tools ….. but unfortunately I get even get passed the first step within your detailed explanation

    Anyway, apologies for the rant :-)

    I really need to get some work done, unfortunately after the last four hours the enthusiasm has some what deteriorated …

    Best Regards


  31. Ben Frain

    Hi Ben,

    No, you probably don’t need that now. I think the only bit you need to check is the General section, titled ‘Enable CSS source maps’. BTW – you’ll notice that the Google link you have posted actually links back here at the end as a reference post. :)

  32. Kalimati

    I’ve setup on Ubuntu 12.04. However, it is not processing the scss file. Throws up this error:
    Running “sass:dist” (sass) task
    Warning: must provide pattern Use –force to continue.
    Any idea where the problem could lie?

  33. John


    I’ve gone through and tried your tutorial. I’m working on Mac OSX 10.6.8 with Chrome v33. I’m using Grunt 0.4.1 and Sass 3.3.0. I’ve edited my Gruntfile.js accordingly (all I really want is sourcemap at this time, not looking for livereload), and I’m not getting any .scss files in the dev tools in either the Elements section or the Network section.

    Has anything changed since the time of your last update that would explain this? I’d enjoy any direction you could give. I’m trying to do some simple wireframing on Zurb Foundation 5 and would like to have sourcemap activated for future development.



  34. Andrew

    Seems odd you have included a link to this information in your excellent book “Sass and Compass for Designers”, yet if you choose to do this, it stops you from using Compass.

  35. Ben Frain

    @Andrew, I’m not using Compass on any of my current projects so can’t easily test however my understanding is source maps now work with Compass. Can you confirm which version of Sass and Compass you are using?

  36. Andrew

    Hi Ben, thank you for the very quick response. I can confirm I am using the following:

    Sass v 3.3.7 (Maptastic Maple) and Compass 1.0.0.alpha.19. Also, grunt-contrib-compass v0.8.0.

    I’m a relative beginner, so am finding the huge amounts of disparate info regarding getting this working a little confusing.

  37. Andrew Jones

    Hi Ben, thanks for getting back to me. I hadn’t fount this information thus far. But using the examples given and everything is working fine.

Leave a Reply

Notify me of followup comments via e-mail. You can also subscribe without commenting.

119 days since this post was last revised. It's probable some minor details have changed.
1936 words