devtools-docs/docs/css-preprocessors.html

{{+bindTo:partials.standard_devtools_article}}
<h1>Working with CSS Preprocessors</h1>

<p>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.</p>

<p>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.</p>

<figure class="screenshot"> <img src="css-preprocessors-files/sass-debugging.png" alt="Elements panel showing .scss stylesheet" /></figure>

<p>To jump to the source file: </p>
<ul>
<li>Click the link to open the (editable) source file in the Sources panel.</li>
<li><b>Control+click</b> (or <b>Command+click</b>) on any CSS property name or value to open the source file and jump to the appropriate line.</li>
</ul>

<figure class="screenshot"><img src="css-preprocessors-files/sass-sources.png" alt="Sources panel showing .scss file" /></figure>

<p>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. </p>

<aside class="note">Changes made in an <em>external</em> editor are not detected by DevTools until the Sources tab
containing the associated source file regains focus. Also, manual editing of a CSS file generated by the Sass/LESS/other compiler will break the source map association until the page is reloaded.</aside>

<aside class="note">If you're using Workspaces, you'll need to make sure the generated CSS file is also mapped into the workspace. You can verify this by looking in Sources panel right-side tree, and seeing the CSS is from your local folder.</aside>


<div class="collapsible">
<h2 id="toc-requirements">Requirements</h2>

<p>There are a few requirements to note when working with a CSS preprocessor:</p>

<ul>
<li><p>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).</p></li>

<li><p>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.</p></li>

<li><p>
You must be accessing your site or app from a web server (not a <b>file://</b> URL), and
the server must serve the CSS files as well as the source maps (.css.map) and source files (.scss, etc.).
</p></li>
<li>
<p>
If you are <em>not</em> using the Workspaces feature, the web server must also supply the
<code>Last-Modified</code> header. The Python <code>SimpleHTTPServer</code> module provides this header by default.
You can start a web server to serve the contents of the current directory like this:</p>
<pre class="prettyprint">python -m SimpleHTTPServer</pre>
</li>
</ul>

</div>
<div class="collapsible">
<h2 id="toc-enabling-css-source-maps">Enabling CSS source maps</h2>

<p>CSS source maps are enabled by default. You can choose to
enable automatic reloading of generated CSS files. </p>

<p><strong>To enable CSS source maps and CSS reload:</strong></p>

<ol>
<li><p>Open DevTools Settings and click <b>General</b>.</p></li>
<li><p>Turn on <b>Enable CSS source maps</b> and <b>Auto-reload generated CSS</b>.</p></li>
</ol>


</div>
<div class="collapsible">
<h2 id="toc-using-css-source-maps">Using Sass with CSS source maps</h2>

<p>To live-edit Sass files in Chrome you need to have the <a href="http://sass-lang.com/download.html">pre-release version of the Sass compiler</a>, which is the only version that currently supports source map generation.</p>

<pre class="prettyprint">gem install sass</pre>


<p>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: </p>

<pre class="prettyprint">sass --watch <b>--sourcemap</b> sass/styles.scss:styles.css</pre>


</div>
<div class="collapsible">
<h2 id="toc-css-preprocessor-support">CSS preprocessor support</h2>

<p>DevTools supports the <a href="https://docs.google.com/a/google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit#">Source Map Revision 3 proposal</a>. This proposal is being implemented in several CSS preprocessors (Updated August 2014):</p>

<ul>
<li><strong>Sass</strong>: As described above, this is supported in Sass 3.3.</li>
<li><strong>Compass</strong>: The <code>--sourcemap</code> flag was <a href="http://compass-style.org/blog/2014/08/15/omg-compass-1-0/">implemented in Compass 1.0</a>. Alternatively you can add <code>sourcemap: true</code> to your config.rb file. <a href="https://github.com/grayghostvisuals/sourcemaps">Demo repo here</a>. Development notes are in <a href="https://github.com/Compass/compass/issues/1108#issuecomment-52432075">issue 1108</a>.
<li><strong>Less</strong>: Implemented in 1.5.0. See <a href="https://github.com/less/less.js/issues/1050#issuecomment-25566463">issue #1050</a> for details and usage patterns.</li>
<li><strong>Autoprefixer</strong>: Implemented in 1.0. <a href="https://github.com/ai/autoprefixer#source-map">Autoprefixer docs</a> explain how to use it, along with absorbing an input sourcemap (from another preprocessor).</li>
<li><strong>Libsass</strong>: <a href="https://github.com/hcatlin/libsass/commit/366bc110c39c26c9267a1cc06e578beb94cd93ef">Implemented</a>.
<li><strong>Stylus</strong>: Implemented.  See the latest in <a href="https://github.com/LearnBoost/stylus/pull/1655#issuecomment-52826158">issue #1655</a>.</li>
</ul>

</div>
<div class="collapsible">
<h2 id="toc-how-css-source-maps-work">How CSS source maps work</h2>

<p>For each CSS file it produces, the preprocessor generates a <a href="http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/">source map</a> 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:</p>

<pre class="prettyprint">
/*# sourceMappingURL=&lt;url&gt; */
</pre>

<p>For instance, given an SCSS file named <b>styles.scss</b>:</p>

<pre class="prettyprint lang-css">
$textSize: 26px;
$fontColor: red;
$bgColor: whitesmoke;

h2 {
    font-size: $textSize;
    color: $fontColor;
    background: $bgColor;
}
</pre>

<p>Sass generates a CSS file, <b>styles.css</b>, with the sourceMappingURL annotation:</p>

<pre class="prettyprint lang-css">
h2 {
  font-size: 26px;
  color: red;
  background-color: whitesmoke;
}
/*# sourceMappingURL=styles.css.map */
</pre>

<p>Below is an example source map file:</p>

<pre class="prettyprint">
{
  "version": "3",
  "mappings":"AAKA,EAAG;EACC,SAAS,EANF,IAAI;EAOX,KAAK"
  "sources": ["sass/styles.scss"],
  "file": "styles.css"
}
</pre>

</div>
<div class="collapsible">
<h2 id="toc-resources">Resources</h2>

<p>Many users have developed their own workflows using CSS preprocessors.
See the following external articles for tutorials and alternate workflows.
</p>

<ul>
<li><a href="https://medium.com/what-i-learned-building/b4daab987fb0">Getting started with CSS sourcemaps and in-browser Sass editing</a></li>
<li><a href="http://benfrain.com/add-sass-compass-debug-info-for-chrome-web-developer-tools/">Faster Sass debugging and style iteration with source maps, Chrome Web Developer Tools and Grunt</a></li>
</ul>

<aside class="note"><strong>Note:</strong> External resources may not reflect the latest version of Chrome.</aside>
</div>
{{/partials.standard_devtools_article}}