Sunday, July 14, 2013

Getting started with CSS sourcemaps and in-browser Sass editing

CSS sourcemaps and in-browser Sass editing

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",
  "mappings": "4DAUA,qFAWQ,CACJ,OAAO,CAAE,KAAK,CAOlB,…",
  "sources": ["../sass/_vars.css”,”../sass/styles.scss"],
  "file": "styles.css"

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

Enable Chrome's CSS sourcemap support

Firstly, make sure you're using Chrome Canary. Secondly, CSS source maps are an experimental dev tools feature, so you'll have to enable the "Developer Tools Experiments" flag in chrome://flags/.

CSS sourcemaps and in-browser Sass editing

Now open your developer tool settings,

CSS sourcemaps and in-browser Sass editing

and under Experiments enable "Sass stylesheet debugging"

CSS sourcemaps and in-browser Sass editing

That's it for configuring Chrome for Sass sourcemap support. Next is to verify everything is working using the Elements panel.

Inspect an element on the page using the element inspector. In the properties list, instead of your styles.css file you should now see the original sourcefile name and line number, in this case "styles.scss:63".

CSS sourcemaps and in-browser Sass editing

If your source files are in a publicly accessible location you can click the filename and it will open in the Sources panel; no extra steps required.

For this example, 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

Chrome workspaces are 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.

CSS sourcemaps and in-browser Sass editing

CSS sourcemaps and in-browser Sass editing

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

CSS sourcemaps and in-browser Sass editing

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".

CSS sourcemaps and in-browser Sass editing

Choose the matching file from your workspace:

CSS sourcemaps and in-browser Sass editing

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:

CSS sourcemaps and in-browser Sass editing

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

CSS sourcemaps and in-browser Sass editing

You can also command-click on a single property:

CSS sourcemaps and in-browser Sass editing

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

CSS sourcemaps and in-browser Sass editing

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 rework or Grunt, 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.