What’s a CSS Sourcemap?

What’s a CSS Sourcemap?

October 9, 2018

A CSS sourcemap is a map for your browser, telling it information about the source files (.less, .scss, etc.).

They’re useful when you’re using CSS preprocessors like Sass or Less (or a CSS minifier) and using your browsers dev tools to debug CSS. For instance, on the ‘Elements’ tab in Chrome’s dev tools selecting an element allows you to see the CSS rule set.

Chrome’s Dev Tools without a CSS sourcemap.

What it shows next to the rule set is the file, and in my case it’s style.css. This rule set lives in style.css. Great.

However, I didn’t author this rule set in style.css. I used Gulp to compile a whole bunch of small, modular .scss files in to a single style.css file. So, Chrome’s reference to the compiled CSS file isn’t that helpful. I can’t blame it on Chrome though. I’m using Gulp to compile my Sass into CSS. And, I never told Chrome that.

Enter CSS sourcemaps

A CSS sourcemap will tell Chrome all the information it needs to identify the exact source file and line number.

Chrome’s Dev Tools with a CSS sourcemap.

Notice that next to the rule set it tells me more information, specifically to look for this ruleset at line 15 of _image-credits.scss. This is super helpful. Light years more helpful than telling me about the compiled output file, style.css.

Visual Studio Code showing the rule set indeed lives on line 15.

How to get in on these sourcemaps

I use Gulp usually to compile less into css, as well as to generate the sourcemaps:

//do sass related stuff
gulp.task('sass', function() {
  //look in the 'sass' folder for any .scss files
  return gulp.src('sass/*.scss')
  //sourcemaps start
      //process sass to css
      .pipe(sass({outputStyle: 'compressed'}))

    //sourcemaps end
    //output .css file to the 'css' folder

Above is a small portion of my Gulpfile.js that compiles my .scss to .css only to display how the sourcemaps are written after the Sass task completes. I’m not going to explain how to use Gulp to compile Sass into CSS but this might give you an idea of “generally” what that process looks like.

The end result is that a sourcemap file is created. And, the CSS file has a note at the bottom which provides instructions to the browser on where to look for the sourcemap.

CSS file with instructions for the browser on where to look for the sourcemap.

The sourcemap file is in the ‘maps’ folder. Here’s what that file looks like:

The actual sourcemap file.

The actual sourcemap file starts off with an array of all the sass file names. After that though, it becomes rather incomprehensible. But, this incomprehensible code provides rich instructions to the browser on how the .css file relates back to all the source files it originated from, which it can then relay back to us through the browser’s dev tools.


Pretty cool, right? For more information on setting up Sourcemaps in Gulp start at the NPM’s gulp-sourcemaps

Image credit: Map SVG credit Unlimiticon via The Noun Project

Mastering CSS: Book by Rich Finelli
Mastering CSS, the Book! Flexbox, Layout, Animations, Responsive, Retina, and more!
Mastering CSS, 2nd Edition, video course by Rich Finelli
Mastering CSS, Second Edition: 47 videos on how to make websites like a boss! Flexbox, Animations, Responsive, Retina, and more!
Back to top