Compass Sourcemaps

Today is a proud day for all Compass users because not only does Compass support sourcemaps, but both work across the board with many popular build tools we have available. In light of the amazing work from everyone who helped bring this feature to fruition, I think its important to see where we’ve come from briefly.

Back in 2012, Chris Epstein opened the issue “Sourcemap support” and if you were one of the lucky ones to track this issue you know it was a long thread with many complaining sourcemaps were either broken or inquiring when they will finally work. I won’t go into specifics, but the short end of the stick is that when sourcemaps are enabled, Compass needed to call a different Sass engine API in order to write the source map file to the location provided by the Compass config not to mention the actual sourcemap file was not being generated for some time. I’m sure there is more than I’m touching on here, but the important part is that all these issues have been resolved! MOVING. ON.

Fast forward to 2014 and the landscape is much different. Since the release of Compass v1.0.0 we’ve seen sourcemaps supported across the board. This means tools like Gulp and Grunt (including their compass compiler helpers), CodeKit2 and the CLI will now produce a Compass sourcemap file that looks a bit like this: style.css.map. Notice the .map portion of the file extension. This is what’s used by your DevTools in order to track the compiled CSS back to the original source. The source map file is a JSON file that defines a mapping between each generated CSS declaration and the corresponding line of the source file. Lets take a look at the config landscape across various tooling systems…

---

Gulp-Compass

For those that use gulp-compass you can do the following in your gulpfile.js in order to enable sourcemaps:

gulp.task('styles', function() {
    return gulp.src('css/sass/styles.scss')
        .pipe(compass({
            config_file: 'config.rb',
            sourcemap: true,
            debug : true,
            css: 'css',
            sass: 'css/sass'
        }))
        .pipe(gulp.dest('css'));
});

Notes:
You can place the sourcemap boolean in your config.rb or you can keep it as I’ve indicated above with your Gulp file. Both ways will work however, you must specify your CSS and Sass directory from your gulpfile.js depicted in the config above. In case you’re still confused here’s that example in the flesh:

gulp.task('styles', function() {
    return gulp.src('css/sass/styles.scss')
        .pipe(compass({
            config_file: 'config.rb',
            css: 'css',
            sass: 'css/sass'
        }))
        .pipe(gulp.dest('css'));
});

gulpfile.js

sourcemap = true

Compass config.rb

---

Gulp-Ruby-Sass

For the gulp-ruby-sass lovers you can do the following via your gulpfile.js…

gulp.task('styles', function() {
    return gulp.src('css/sass/styles.scss')
        .pipe(sass({
                compass: true,
                sourcemap: true
            })
        )
        .pipe(gulp.dest('css'));
});

Notes:
Again, same situation as gulp-compass. You can simply remove the sourcemap: true line and add sourcemap = true to your config.rb instead.

---

Grunt Contrib Compass

For grunt-contrib-compass you can place this snippet below within your grunt.initConfig({}) wrapper.

compass: {
    dist: {
        options: {
            config: 'config.rb',
            sourcemap: true
        }
    }
}

Notes:
Of course in this case you could also place the sourcemap boolean within your config.rb instead of declaring it in your Grunt file. Pick your poison as they say.

---

CodeKit2

For CodeKit2 all you need to add is a line in your config.rb and let CodeKit do the rest!

sourcemap = (environment == :development) ? true : false;

If you don’t desire environment detection you can set the sourcemap value to true like so…

sourcemap = true;

---

CLI Commando Style

If you want to go the CLI route you can run this line from your Terminal, but you should also have a config.rb present as well.

sass --compass --sourcemap --watch css/sass/styles.scss:css/styles.css

---

Deep Diving…

If you’re interested in diving down the rabbit hole further with sourcemaps there are a handful of articles out there, but your best bet is to visit the demo repo I’ve created (also listed on the DevTools Documentation) to get a feel for each tool generating sourcemaps with Compass. If you need to understand how to map your Sass files to your DevTools refer to the DevTools Documentation that details each part of the process step by step -or- you can read about the setup on Hacks.Mozilla that was implemented dating back to Firefox 29!

Links

• Sourcemaps Demo Repo:
  https://github.com/grayghostvisuals/sourcemaps
• DevTools Docs:
  https://developer.chrome.com/devtools/docs/css-preprocessors
• Chris Eppstein – The Mind-blowing Power of Sass 3.3:
  http://www.youtube.com/watch?v=-ZJeOJGazgE
• Compass Config Documentation:
  http://compass-style.org/help/documentation/configuration-reference