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"

Usage

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

• Bundler official site
• Bundler on Github
• Managing Compass Extensions with Bundler
• Avoiding Sass Version Differences with Bundler