Quinn Labs: A website about building websites

bundler cover

Bundler for compass & sass version management, using Mac OS X and homebrew

Problem: Compass, the sass framework for building CSS, often isn’t backward-compatible after updates, so how can we maintain/update the CSS on existing sites without starting from scratch?

Solution: Bundler, the easy way to have per-project versions of compass & sass.

We usually build the CSS for our projects with compass, because it has a rich set of extensions and mixins that speed up the task of building modern, responsive sites. The problem we’ve run into is that, when the CSS needs to be updated, the current version of compass may not be able to compile the CSS. Ideally, we’d be able to use the historical versions of compass and sass that we used to build the site originally. Bundler makes that possible, even easy. If you’re familiar with PHP’s composer tool, bundler does a similar job for ruby.

Because we like to avoid modifying the system software, we used homebrew to install a local copy of ruby, even though OS X comes with its own copy of ruby. This ensures that system updates won’t remove what we’ve set up. We especially like homebrew because it doesn’t require the potentially hazardous use of root privileges with sudo. You need ruby to run compass and sass.

Below are the simple steps we took to start using bundler. These are command-line steps done in Terminal.

One-time installation

  1. brew install ruby
  2. Close the Terminal window and start a new one to ensure your commands will use the newly installed ruby and related software.
  3. gem install bundler

Project set-up

  1. Change directory to where your compass config.rb file is.
  2. bundle init—this creates a file named Gemfile.
  3. Edit Gemfile as shown below.

In this example, we’re locking sass version 3.2.9 and compass 0.12.2. You can use more sophisticated version constraints. For example, we could have written gem 'compass', "~>0.12.2" to enable upgrades to compass up to, but not including, 0.13.0.

source "https://rubygems.org"
gem 'sass', "3.2.9"
gem 'compass', "0.12.2"


Prefix usual commands with bundle exec, as in these examples:

  • bundle exec compass watch -e development
  • bundle exec compass compile -e production

Other commands:

  • bundle install—use this if bundle tells you a dependency is missing
  • bundle update—safely update bundled software while respecting the version constraints you’ve specified.

What to commit to your version control system (git, svn)

Check in and commit the Gemfile and Gemfile.lock files.

Further reading

About the Author

  • Fred Condo

    Fred has a Ph.D. in the Management of Information Systems and Cognitive Psychology from Claremont Graduate School, and is Chief Engineer at Quinn Interactive. He taught a graduate level class, “Principles of Usability” at the Academy of Art in San Francisco, and was an Assistant Professor in the Communication Design department at California State University, Chico for 6 years, teaching web development and human factors. Fred got into SilverStripe in 2008. He has made 35 commits to the SilverStripe framework repository, which makes him the 36th-most prolific contributor to the project (as of November 2014). You should follow him on GitHub here.

    More from Fred Condo