Getting started with CSS sourcemaps and in-browser Sass editing

Tim Lucas
5 min readJul 9, 2013
The end result: command-click a property, inspect the source, edit the Sass in-browser, and see the changes appear live.

CSS sourcemaps allow the browser to map CSS generated by a pre-processor, such as Sass, back to the original source file, including exactly which Sass mixin, placeholder or variable is responsible for a given line of CSS. And when you combine sourcemaps with Chrome’s new in-browser local file editing (workspaces) and automatic stylesheet reloading, you end up with a very fast in-browser editing workflow.

So refill your CSS is awesome mug and boot up Chrome Canary, it’s time to get up-and-running with these two new features.

Install Sass 3.3+

At the moment sourcemap support is only available in the yet-to-be-released Sass 3.3, which you can install with the following voodoo:

gem install sass -v '>=3.3.0alpha' --pre

With or without sudo, depending on how you roll.

Configure Sass

Once you have the latest Sass you simply use the new sourcemap flag:

scss --sourcemap sass/styles.scss public/styles.css

If you tried this before Sass 3.3 you’ll notice this is different to the old debug-info syntax. That syntax has now been deprecated and won’t work in Chrome Canary or future versions of Chrome.

If you want Sass to automatically recompile the CSS whenever the SCSS file changes (you’ll want this later when editing the Sass in-browser), use the watch flag and specify the input:output directories.

scss --sourcemap --watch sass:public

If you inspect your compiled CSS file you should should now see a sourcemap statement on the last line:

/*# */

and there’ll be a file, looking similar to:

"version": "3",
"sources": ["../sass/_vars.css”,”../sass/styles.scss"],
"file": "styles.css"

That’s it for adding a sourcemap to your CSS.

Verify source maps are working

The latest version of Chrome Canary as CSS and Javascript source maps enabled by default.

If you had a previous version of Chrome Canary installed you might need to enable CSS source maps under dev tools General settings.

To see your source map in action, simply open the Elements inspector and in the properties list instead of your styles.css file you should now see the original source file name and line number, in this case styles.scss:63

If your source files are in a publicly accessible location you can click the filename, in this case styles.scss:63, and it will open in the Sources panel; no extra steps required.

In this case the original SCSS source isn’t accessible to the public, so clicking those links will only take you to an empty page in the Sources panel. To fix this we need to create a workspace and a remote-to-local file mapping.

Create a workspace

Your Chrome workspace is how you give Chrome permission to access the file system, and to have those files show up in your Sources panel.

Open your developer tools settings, and under Workspace add your site’s root folder.

If you open the Sources panel, and expand the sidebar, you’ll now find your local files listed alongside remote files.

Create a file mapping

We need to map the remote sass file, which was returning a 404, to one of the local files in your newly setup workspace.

Find the remote, non-existing Sass file from your site’s sources, and choose “Map to File System Resource”

Choose the matching file from your workspace:

Finally you’ll be asked to restart Chrome dev tools.

If you return to your elements inspector and hover over the filenames you should now see they point to local file paths:

and if you follow that link it should open up in the Sources panel, highlighting the line in the original source:

You can also command-click on a single property:

and be taken to the line for that specific property, whether it’s in a mixin, placeholder selector, or otherwise:

Auto-reloading your stylesheet

Whenever a Sass file is saved in Chrome it will attempt to reload it from the server so you can see your changes instantly. For this to work you need to ensure your Sass files are being recompiled whenever your files are modified. Starting Sass with the --watch flag will keep Sass running indefinitely, watching for any file changes and recompiling them as soon as they’re modified.

Tool support

Sass is the only CSS processing tool capable of generating sourcemaps at the moment, thanks to the Chrome dev tools team contributing the initial sourcemap support to Sass and Nathan Weizenbaum getting it ready for release. And Chrome Canary is the only browser capable of understanding them. But it’s an open format, based on the Javascript sourcemap which already has wide browser support, so it shouldn’t be long before we see it across the other browsers.

And as far as getting support in other CSS processing tools, such as Less, rework and Compass, well it’s time to get forking!

Thanks to Paul Irish, Ben Schwarz, Casey Leask, and Diana Mounter for their feedback whilst putting together this guide.



Tim Lucas

Founder, CPO, designer and engineer at @buildkite. A Venn diagram of cats, coffee, the web, design, photography and programming. Twoots as @toolmantim