Using Source Maps to Debug Sass in Chrome

If you use Sass in your front-end projects, chances are your partials are split in a clean and logical fashion based on a reliable Sass architecture.

In such cases, debugging the compiled CSS could be both troublesome and time consuming. Sass provides a flag to enable line numbers (--line-numbers), which includes comments (like below) in your CSS.

/* line 303, molecules\accordions\_accordions.scss */

Although this is helpful, you would still have to trace the bug in your CSS back to the source file manually. And editing the CSS in the browser using the developer tools cannot be persisted, since it will get overwritten by the next Sass compile.

So how can we make this process easier?

I’m going to show you how to use source maps in conjunction with Chrome’s Workspaces to allow you to debug and edit Sass from within the browser.

Browser and Sass Requirements

The source maps feature gained a lot of attention when it was first introduced and a lot has changed since. It is now available in the latest stable versions of Chrome, Firefox, and Safari.

You do not require Chrome Canary, nor do you need to edit chrome://flags to use this. You only have to apply the correct settings to enable it.

Source maps require Sass 3.3 or above (Sass 3.4 was released recently).

What is a Source Map?

A source map is a .map file in JSON format that gets generated when your Sass files are compiled into CSS. It contains information that links each line of your CSS file (the output) to the corresponding line in its SCSS source file (the input).

This means when your CSS is compiled, you’ll see a comment like the following at the end of your compiled CSS file:

/*# sourceMappingURL=style.css.map */

Below is the content of a truncated .map file.

{
"version": 3,
"mappings": ";AAiIA,qDAAsD;EACpD,OAAO,EAAE,GAAG"
"sources": ["../scss/foundation/components/_breadcrumbs.scss","../scss/foundation/components/_icon-bar.scss","../scss/foundation/components/_offcanvas.scss","../scss/foundation/components/_visibility.scss","../scss/foundation/components/_global.scss","../scss/foundation/pages/_index.scss"],
"names": [],
"file": "foundation.css"
}

How Do Source Maps Help?

When debugging a web page using Chrome’s developer tools using source maps, the styles panel will show which Sass partial your CSS came from instead of pointing to the CSS file. Meaning, instead of showing the source as style.css, it will show it as _buttons.scss.

In the example in the screenshot below, the styles for the body element come from a partial called _body.scss.

When inspecting, I would like to know where I have defined the color: black portion in this.

To get this information, I could perform one of the following actions to inspect further:

1. Press CTRL and click on the word color. It will open the appropriate partial in the sources tab and place the cursor in the exact line where the style is defined. In this case, the color is defined in a variable called $black.
2. Press CTRL and click on the word black. It will open _colors.scss in the sources tab, where the value for the variable $black is defined. In case the color black was coming from a mixin instead of a variable, CTRL + clicking on it will open the file where the mixin is defined. Click the image below to view an animated GIF that shows a demonstration of how this might look.

Using source maps with Workspaces allows you to edit and save changes from within Chrome’s developer tools. If sass --watch is running, it will detect the change and recompile the CSS. The browser will then automatically reload this new CSS.

Enabling Source Maps in node-sass Plugins

All the node-sass plugins have APIs to enable the Sass source map option.

• grunt-contrib-sass – Enable source maps in the options section of your Gruntfile.js to set sourcemap: true.

• gulp-sass sourceComments: 'map' in gulp-sass will enable source maps in Gulp. This inlines the source maps, meaning they are appended to the end of your CSS file itself. There will be no separate .map file in this case.

• broccoli-sass sourceMap: true will enable source maps.

Enabling Source Maps Using the Sass Ruby Gem

If you are using the Sass Ruby gem to compile, you can enable source maps with the following terminal command:

sass style.scss:../css/style.css --sourcemap

Enabling Source Maps Using Compass

If you are using Compass, you can run the following command:

sass style.scss:../css/style.css --compass --sourcemap

Or you can add sass_options = {:sourcemap => true} to your config.rb file and run compass watch as usual.

Enabling Source Maps in Chrome

Enabling source maps will compile a map with references. This compilation will result in two files, a .css file and a .css.map file. The .map file will contain the relevant details to allow you to debug the exact location where a style originates.

To get this working in Chrome, follow the steps below:

1. Open developer tools.
2. Click the gear icon (top right) to open Settings.
3. Under General, look for the “Sources” section. In that section, select “Enable CSS source maps”.
4. Make sure the accompanying “Auto-reload generated CSS” is also enabled.

The last step helps to reload the CSS when it changes. Think of it like a live reload feature for the CSS alone.

Note: You will still have to compile the SCSS separately using Grunt, Gulp, sass watch, or compass watch. Once the CSS has been generated this, feature will auto reload it for you.

Live Editing SCSS in the Browser

Enabling Chrome Workspaces will allow you to persist (if you wish) changes that you make to your actual files in the Chrome web inspector. This way you don’t have to try your changes in the browser, see what works, and then head back to your editor to persist these changes.

To enable Workspaces in Chrome, do the following:

1. Open Chrome developer tools.
2. Click the gear icon to bring up the Settings panel.
3. Choose the “Workspace” option on the left side of the Settings panel.
4. Select your project’s root folder under the “Folders” section.
5. Give Chrome permission to access your local file system.

This will add all your project files to the Sources panel in the developer tools.

Mapping from localhost to File on Disk

The last step to editing SCSS in the browser requires you to map the files from localhost to the source files. Doing the following will enable this mapping:

1. While viewing the page on your localhost server, inspect any element on your page.
2. In the developer tools, choose the Sources tab.
3. In the file tree on the left hand side, right-click your stylesheet and select “Map to file system resource…”.
   
4. This will bring up the file search dialog. Select the appropriate file (your stylesheet).
   
5. Restart the developer tools.

This will connect the file from localhost to the files on the actual drive. Now you can edit your SCSS in the browser and when you save, Chrome will write those changes to the actual file.

If you are watching your Sass for changes, the SCSS will get compiled and the CSS will be auto refreshed in your page including your changes.

Conclusion

Source maps enable you to avoid the hassle of switching between editor and developer tools. It enables you to edit the source SCSS directly and allows you to instantly see how these changes look in the browser.

Although this article focused on making source maps work in Chrome, you can do the same in Firefox, and Safari. Internet Explorer 11 also supports source maps, but there doesn’t seem to be any info on using source maps in that browser with Sass, so you’d have to try it for yourself.

If you like to learn visually, check out SassBites #21 by Micah Godbolt, which discusses how to enable and use source maps in Chrome.

I hope this becomes a valuable, time saving addition to your workflow.

Frequently Asked Questions (FAQs) on Using Source Maps to Debug SASS in Chrome