Compiling Sass with Phpstorm

Compiling Sass with Phpstorm

Published June 10, 2014 in Development
Implementing High-Res Images on Magento’s Native Responsive Theme
May 27, 2014
An In-Depth Look at Magento Theme Fallback
August 5, 2014

When we built the new Magento responsive theme, we decided to use Sass as the CSS pre-processor and Compass as the compiler (technically known as a transpiler). Sass is the base syntax that supports mixins, variables, and nesting and Compass is a compiler that extends Sass’s capabilities by adding CSS3 mixins that we used to make the responsive theme compatible with older browsers. Here is the TL;DR infographic:

CSS vs Sass vs Compass - Captain America Style
Image Source:

You can read all about the basics of working with the new responsive theme over at the Magento knowledge base. In this article, we’re going to take a more in-depth look at how to compile with Compass on the command line and via PhpStorm.


This article assumes that you’ve gone through the Magento RWD documentation and you have a custom Magento theme setup at skin/frontend/custompackage/customtheme.

Compass on the command line

Before you can compile with Compass, you need to install the command-line utility. After you’ve installed Compass, you can compile by running this command:
compass compile <MAGENTO_DIRECTORY>/skin/frontend/custompackage/customtheme
This command will compile your .scss files into .css files, but you have to run this command every time you make a change to your .scss files. To automatically re-compile your .scss files every time there is a change, you can run this command:
compass watch <MAGENTO_DIRECTORY>/skin/frontend/custompackage/customtheme

While it is valuable to know how Compass works on the command-line, many developers use their IDE or a standalone GUI app (like Scout or CodeKit) to compile with Compass. If you are going to do a lot of frontend development with Sass/Compass, I could encourage you to experiment with your different options and choose the approach that best integrates with your workflow. I use PhpStorm, so that is what I use to compile with Compass.

Compiling Compass in PhpStorm

PhpStorm seems to have become the de facto IDE for Magento backend developers, due to its excellent support for features like syntax highlighting, auto-completion and debugging. However, I was skeptical about using a Php-oriented IDE for front end development, as my previous experiences with robust IDEs like Eclipse/PDT provided to be clunky. Prior to PhpStorm, I used apps like CSSEdit/Espresso/TextMate for front end development. However, I found PhpStorm to be a joy to for front end development, as it offers features like CSS/HTML validation, Sass variable auto-completion, and rapid HTML markup creation via it Live Templates. It is now my IDE for frontend and backend development.

PhpStorm has a feature called “File Watcher” that allows you to automatically run Compass any time you change a .scss file. The way this feature works is that any time you make changes to .scss files in PhpStorm, PhpStorm will run a command line call to “compass compile”. Here are the steps for setting up this feature:

  1. Go to “PhpStorm > Preferences” (Cmd + ,)
  2. Type “File Watchers” in the filter input, click the “+” icon, and then click “compass scss” PhpStorm File Watcher Creation
  3. Configure the File Watcher with these settings: PhpStorm File Watcher Compass Configuration
    Notable settings:

    • Immediate File Synchronization: Uncheck this option so that PhpStorm doesn’t compile until you actually save a file. It can get really annoying if PhpStorm is trying to recompile as you’re typing.
    • Trigger watcher regardless of syntax errors: PhpStorm is smart. It knows when you have errors in your code, and you can configure the File Watcher to only compile when your code is error-free. However I find that feature to be confusing — when I had it enabled, I would commonly make a change, save the file, flip over to the front end to wait for my CSS to refresh (via LiveReload), only to realize a minute later that the .scss file wasn’t compiling due to an error. With this option disabled, PhpStorm will try to compile your .scss file and will throw an obvious error, which I find to be more helpful: PhpStorm File Watcher Error
    • Program: This tells PhpStorm which command line utility to run. Since PhpStorm is just running the command line “compass” utility, enter “compass” into this field.
    • Arguments: This field includes the arguments that get passed to the “compass” command above. This field needs to include the location of your custom theme, relative to the root of your PhpStorm directory.
    • Working directory: PhpStorm will take the value from this input and use it as the working directory when running the compass command. NOTE: You must insert this variable using the “Insert Macro…” button. If you just type the “$ProjectFileDir$” text, PhpStorm won’t recognize it.

    So based on the configuration screenshot above, PhpStorm will essentially run these commands any time a .scss file is changed:

If you have multiple themes for which you need to compile .scss files, you simply need to setup File Watchers for each theme. For example: Compass File Watcher Multiple Themes

If you follow these steps, your .scss files should be compiled any time you make a change in PhpStorm!

1 Comment

  1. Samuel Hughes Mensah says:

    can u do a tutorial on how to create a custom filewatcher

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Related postsView all
March 27, 2018

How to Create a Payment Method in Magento 2

Sometimes you might need more than the standard out-of-the-box payment method. Perhaps you have an agreement with a credit card processor and a solution for their […]
March 6, 2018

How to Build a Theme in Magento 2

When building a custom theme for Magento, it’s important to follow best practices for how the system is designed to be extended. Magento 2’s frontend is […]
February 12, 2018

Display Configurable Product Price Ranges in Magento 2

Today we’re going to look at the advantages of using configurable products and how we can update how their prices display on Magento 2 product listing […]
Most Recent PostsView all
November 29, 2018

Llama in the Sunset: David Alger

His stature has him towering well above the other llamas that surround him at Classy Llama. And his worn, size 13 cowboy boots show he’s more […]
October 17, 2018

Llamas and the Mobile eCommerce Optimization Initiative

The Mobile eCommerce Optimization Initiative has kicked off and Classy Llama is participating! The Magento Community has come together to create and test multiple conversion optimization […]
June 7, 2018

From Brick-and-Mortar To Online: How to Connect with a Niche Audience

As an eCommerce business, every penny counts. If you want to be successful, you have to carefully balance spending money to generate business and the profits […]