school Are you a developer in an agency in the UK, Indonesia or India? Find out more about our free 2 day Progressive Web Apps training .

Set Up CSS and JS Preprocessors

CSS preprocessors such as Sass, as well as JS preprocessors and transpilers can greatly accelerate your development when used correctly. Learn how to set them up.

TL;DR

  • Preprocessors let you use features in CSS and JavaScript that your browser doesn't support natively, for example, CSS variables.
  • If you're using preprocessors, map your original source files to the rendered output using Source Maps.
  • Make sure your web server can serve Source Maps.
  • Use a supported preprocessor to automatically generate Source Maps.

What's a preprocessor?

A preprocessor takes an arbitrary source file and converts it into something that the browser understands.

With CSS as output, they are used to add features that otherwise wouldn't exist (yet): CSS Variables, Nesting and much more. Notable examples in this category are Sass, Less and Stylus.

With JavaScript as output, they either convert (compile) from a completely different language, or convert (transpile) a superset or new language standard down to today's standard. Notable examples in this category are CoffeeScript and ES6 (via Babel).

Debugging and editing preprocessed content

As soon as you are in the browser and use DevTools to edit your CSS or debug your JavaScript, one issue becomes very apparent: what you are looking at does not reflect your source, and doesn't really help you fix your problem.

In order to work around, most modern preprocessors support a feature called Source Maps.

What are Source Maps?

A source map is a JSON-based mapping format that creates a relationship between a minified file and its sources. When you build for production, along with minifying and combining your JavaScript files, you generate a source map that holds information about your original files.

How Source Maps work

For each CSS file it produces, a CSS preprocessor generates a source map file (.map) 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 Sass source 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"
}

Verify web server can serve Source Maps

Some web servers, like Google App Engine for example, require explicit configuration for each file type served. In this case, your Source Maps should be served with a MIME type of application/json, but Chrome will actually accept any content-type, for example application/octet-stream.

Bonus: Source mapping via custom header

If you don't want an extra comment in your file, use an HTTP header field on the minified JavaScript file to tell DevTools where to find the source map. This requires configuration or customization of your web server and is beyond the scope of this document.

X-SourceMap: /path/to/file.js.map

Like the comment, this tells DevTools and other tools where to look for the source map associated with a JavaScript file. This header also gets around the issue of referencing Source Maps in languages that don't support single-line comments.

Supported preprocessors

Just about any compiled to JavaScript language has an option to generate Source Maps today – including Coffeescript, TypeScript, JSX and many more. You can additionally use Source Maps on the server side within Node, in our CSS with via Sass, Less and more, using browserify which gives you node-style require abilities, and through minification tools like uglify-js which also adds the neat ability to generate multi-level Source Maps.

JavaScript

Compiler Command Instructions
CoffeeScript $ coffee -c square.coffee -m The -m (--map) flag is all it takes for the compiler to output a source map, it will also handle adding the sourceMapURL comment pragma for you to the outputted file.
TypeScript $ tsc -sourcemap square.ts The -sourcemap flag will generate the map and add the comment pragma.
Traceur $ traceur --source-maps=[file|inline] With --source-maps=file, every output file ending in .js will have a sourcemap file ending in .map; with source-maps='inline', every output file ending in .js will end with a comment containing the sourcemap encoded in a data: URL.
Babel $ babel script.js --out-file script-compiled.js --source-maps Use --source-maps or -s to generate Source Maps. Use --source-maps inline for inline Source Maps.
UglifyJS $ uglifyjs file.js -o file.min.js --source-map file.min.js.map That is the very basic command needed to generate a source map for 'file.js'. This will also add the comment pragma to output file.

CSS

Compiler Command Instructions
Sass $ scss --sourcemap styles.scss styles.css Source Maps in Sass are supported since Sass 3.3.
Less $ lessc styles.less > styles.css --source-map styles.css.map Implemented in 1.5.0. See issue #1050 for details and usage patterns.
Stylus $ stylus --sourcemaps styles.style styles.css This will embed the sourcemap as a base64 encoded string directly in the out file.
Compass $ sass --compass --sourcemap --watch scss:css Alternatively you can add `sourcemap: true` to your config.rb file.
Autoprefixer Follow the link to see how to use it and absorb an input sourcemap.

Source Maps and DevTools

Now that you've got Source Maps properly set up, you might be happy to learn that DevTools has built-in support for both CSS and JS based Source Maps.

Editing preprocessed CSS

Head over to Edit Sass, Less or Stylus to learn more about how to edit and refresh styles linked to a source map directly within DevTools.

Editing and debugging preprocessed JavaScript

Learn more about how to debug minified, compiled or transpiled JavaScript in the Sources Panel in Map Preprocessed Code to Source Code.