Setting up SASS & Compass for your Drupal 8 Theme

Apr 18, 2016 · by Jorge Diaz

Note: This material is part of the materials of our Drupal 8 Theming Training Course. We'll guide you through the process of using SASS with your Drupal 8 theme. Most of this information also applies to Drupal 7 and non-Drupal websites.

What are SASS and Compass and why would I need them?

SASS (Syntactically Awesome Stylesheets) is a scripting language that generates CSS code. It's become very popular due to the way it speeds up your CSS development, makes your code easier to read and reuse.

SASS files are just CSS files, but they support extra features such as nested rules, variables, mixins and selector inheritance. Here's what one looks like:

// Mixin Definition and usage
@mixin border-radius($radius) {
    -webkit-border-radius: $radius;
    -moz-border-radius: $radius;
    border-radius: $radius;
.my-other-element {
    @include border-radius(5px);

// Variables
$primary-color: hotpink;
.my-element {
    color: $primary-color;
    width: 100%;
    overflow: hidden;

// Support for Nested Rules
#main-content {
  color: black;
  .field {
    color: blue;

To take advantage of SASS features, just put this code .scss file (think of it as "SASS-CSS"), and run it through.

Then you need to use Compass, a simple command-line tool compiles the source .scss files into generated .css files, which all the browsers know how to parse, and that you can include in your theme.

The great thing about SCSS syntax is that all existing CSS files are also valid SCSS files, so you can copy and paste all your existing CSS and add features as you need to.

WARNING: Confusingly enough, Compass can also compile two other very similar syntaxes for CSS preprocessing, in the form of .sass and .less files. The .sass files use an older syntax for SASS (known as indented syntax), while .less uses a competing library (called LESS) that's very similar but has less adoption.

Let's proceed to install compass and sass and use it as part of our theme.

Setting up the theme folder

    $ gem update --system
    $ gem install compass sass
  1. Install SASS and Compass via the command line ensure to have Ruby installed in your environment.
  2. In your Drupal theme folder, create a new file and name it "config.rb", and make sure it contains the following:
# We tell compass that we want to use. SCSS format in this case
preferred_syntax = :scss

# Where we want our CSS files to go
css_dir = 'css'

# Where we want to put our source SASS Files
sass_dir = 'sass'

# While in Dev, we can use this feature to easily debug the CSS styles
line_comments = true

Alternatively, the following command will generate config.rb for you inside your theme directory (themes/THEME-NAME):

compass create themes/THEME-NAME --css-dir=css --sass-dir=sass


Move your existing stylesheet to SASS

Because every valid CSS file is also a valid SCSS file, you only need to rename the file, put it in the right place, and run you can start using SASS features in it.

Let's see how to add SASS support to your theme's css/style.css. With the configuration we put into config.rb, compass will parse each file located in sass/FILE.scss and output a corresponding css/FILE.css.

  1. Create a new directory inside your theme folder named sass
  2. Move css/style.css to the new sass/ folder
  3. Rename the file from style.css to style.sass

To include css/style.css in your D8 theme, make sure THEME-NAME.libraries.yml contains the following:

      css/style.css: {}

Now we will have the following set up in our theme folder:

  • /css/ Where CSS files will be generated.
  • /sass/ Where the source SASS files will be placed.
  • /config.rb The configuration file that Compass will use to run in our theme folder.

Ok, now we will go to a console and will "cd" into the theme folder:

cd themes/custom/THEME-NAME/

And run the following command:

compass watch

Compass watch will check for changes in the /sass folder . Just make sure to keep the Terminal/Console window open while developing with SASS. Compass will be passively waiting for changes in the SASS files to recompile again.

>>> Compass is watching for changes. Press Ctrl-C to Stop.
    write css/style.css
 modified sass/style.scss
    write css/style.css
 modified sass/style.scss
    write css/style.css

Now save the style.scss file. Open the /css/style.css file to see the results. You are now compiling your CSS with Compass!

As you have noticed, we haven't done any "Drupal-specific" setup. This process could have been done in any folder of any existing website, no matter what technology it uses.

Setup your SASS Debugging Tools

As a bonus, I'll explain how to debug SASS (*.sass/*.scss) files when inspecting the page layout using Firebug and the FireCompass extension.

  1. Go to the FireCompass extension page and install it in your browser:
  2. Add it to Firefox and enable the extension.
  3. Reload the page and inspect the layout as usual.

NOTE: For debugging SASS in Google Chrome, please refer to

Want to read more?

The use of SASS is becoming a major trend in the web development world. Many popular front-end frameworks such as Bootstrap 4 and Bourbon have moved completely to SASS.

Bootstrap 4 has moved to SASS

At Evolving Web, we have a SASS chapter in our Drupal 8 Theming Training Course.

If you're interested in SASS-specific resources, you can take a look at the following links: