Contents
- Requirements
- Enabling CSS source maps
- Using Sass with CSS source maps
- CSS preprocessor support
- How CSS source maps work
- Resources
Many developers generate CSS style sheets using a CSS preprocessor, such as Sass, Less, or Stylus. Because the CSS files are generated, editing the CSS files directly is not as helpful.
For preprocessors that support CSS source maps, DevTools lets you live-edit your preprocessor source files in the Sources panel, and view the results without having to leave DevTools or refresh the page. When you inspect an element whose styles are provided by a generated CSS file, the Elements panel displays a link to the original source file, not the generated .css file.
To jump to the source file:
- Click the link to open the (editable) source file in the Sources panel.
- Control+click (or Command+click) on any CSS property name or value to open the source file and jump to the appropriate line.
When you save changes to a CSS preprocessor file in DevTools, the CSS preprocessor should re-generate the CSS files. Then DevTools reloads the newly-generated CSS file.
Requirements
There are a few requirements to note when working with a CSS preprocessor:
To use this workflow, your CSS preprocessor must support CSS source maps, specifically the Source Map v3 proposal. The CSS source maps must be built along with the CSS files, so DevTools can map each CSS property to the correct location in the original source file (for example, .scss file).
For the DevTools to automatically reload styles when you change the source file, your preprocessor must be set up to regenerate CSS files whenever a source file changes. Otherwise, you must regenerate CSS files manually and reload the page to see your changes.
You must be accessing your site or app from a web server (not a file:// URL), and the server must serve the CSS files as well as the source maps (.css.map) and source files (.scss, etc.).
-
If you are not using the Workspaces feature, the web server must also supply the
Last-Modifiedheader. The PythonSimpleHTTPServermodule provides this header by default. You can start a web server to serve the contents of the current directory like this:python -m SimpleHTTPServer
Currently Sass is the only preprocessor that supports CSS source maps, so this document describes how to work with Sass. Working with other preprocessors should be similar. For more information on the status of source map support in other preprocessors, see CSS preprocessor support.
Enabling CSS source maps
In Chrome 30 and later, CSS source maps are enabled by default. You can choose to enable automatic reloading of generated CSS files.
To enable CSS source maps and CSS reload (Chrome 30 and later):
Open DevTools Settings and click General.
Turn on Enable CSS source maps and Auto-reload generated CSS.
In Chrome 29 and earlier, CSS source maps are included in DevTools experiments and must be enabled explicitly.
To enable CSS source maps and CSS reload (Chrome 29 or earlier):
Open about:flags in Chrome.
Turn on Enable Developer Tools experiments.
Restart Chrome.
Open DevTools Settings and click Experiments.
Turn on Support for Sass (or Sass stylesheet debugging, depending on the browser version you're using).
Click General.
Turn on Auto-reload CSS upon Sass save.
If necessary, you can adjust the Timeout setting, which specifies the delay between the time you update a source file and the time that the browser reloads the CSS files. Timeout is specified in milliseconds, and defaults to 1000 (1 second).
This timeout is eliminated in newer versions of Chrome.
Using Sass with CSS source maps
To live-edit Sass files in Chrome you need to have the pre-release version of the Sass compiler, which is the only version that currently supports source map generation.
gem install sass -v '>=3.3.0alpha' --pre
Once Sass is installed, start the Sass compiler to watch for changes to your Sass source files and create source map files for each generated CSS file, for example:
sass --watch --sourcemap sass/styles.scss:styles.css
If you are using Compass, note that Compass doesn’t yet support the pre-release version of Sass, so you can’t use Sass debugging with Compass.
CSS preprocessor support
DevTools supports the Source Map Revision 3 proposal. This proposal is being implemented in several CSS preprocessors:
- Sass: As described above, this is supported in the prerelease version of Sass.
- Compass: Uses Sass internally but doesn't support source maps yet. Support is scheduled for a future release. See Issue 1293.
- Less: Under development. See issue #1050.
- Stylus: Under consideration. See issue #1072.
How CSS source maps work
For each CSS file it produces, the preprocessor generates a source map file (.map file) in addition to the compiled CSS. 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. Each CSS file contains an annotation that specifies the URL of its source map file, embedded in a special comment on the last line of the file:
/*# sourceMappingURL=<url> */
For instance, given an SCSS file named styles.scss:
$textSize: 26px;
$fontColor: red;
$bgColor: whitesmoke;
h2 {
font-size: $textSize;
color: $fontColor;
background: $bgColor;
}
Sass generates a CSS file, styles.css, with the sourceMappingURL annotation:
h2 {
font-size: 26px;
color: red;
background-color: whitesmoke;
}
/*# sourceMappingURL=styles.css.map */
Below is an example source map file:
{
"version": "3",
"mappings":"AAKA,EAAG;EACC,SAAS,EANF,IAAI;EAOX,KAAK"
"sources": ["sass/styles.scss"],
"file": "styles.css"
}
Resources
Many users have developed their own workflows using CSS preprocessors. See the following external articles for tutorials and alternate workflows.