Compass Deployment & Usage Guide

Note: Compass is no longer actively maintained. This guide is for historical/legacy use. Consider migrating to modern alternatives like Dart Sass or PostCSS for new projects.

1. Prerequisites

• Ruby (MRI) 1.8.7 or newer (tested up to 2.3.x). Newer Ruby versions (3.x+) may have compatibility issues.
• RubyGems (usually included with Ruby)
• Git (for cloning the repository)
• Build tools (for native Ruby gem extensions):
  • macOS: Xcode Command Line Tools (xcode-select --install)
  • Ubuntu/Debian: build-essential, libxml2-dev, libxslt1-dev
  • Windows: Ruby DevKit (matching your Ruby version)

2. Installation

Install Compass Gem

gem install compass

If you encounter permission errors, consider using a Ruby version manager (rbenv/RVM) or sudo gem install compass.

Verify Installation

compass --version
# Should output something like: Compass 1.0.3 (Polaris)

Clone Repository (Optional - for source exploration)

git clone https://github.com/Compass/compass.git
cd compass
# To install from the cloned source (not typically needed):
gem build compass.gemspec
gem install compass-*.gem

3. Configuration

Compass is configured per-project via a config.rb file.

Create a New Compass Project

compass create my_project
cd my_project

This generates:

• config.rb (main configuration)
• sass/ (directory for .scss/.sass files)
• stylesheets/ (output directory for compiled CSS)
• images/, javascripts/ (optional asset directories)

Key config.rb Settings

Edit config.rb to customize:

# HTTP path to assets (for generating correct URLs in CSS)
http_path = "/"

# Directory structure
sass_dir = "sass"
css_dir = "stylesheets"
images_dir = "images"
javascripts_dir = "javascripts"

# Output style (nested, expanded, compact, compressed)
output_style = :expanded

# Enable/disable line comments for debugging
line_comments = true

# Relative paths to assets from CSS
relative_assets = true

4. Build & Run

Development (Watch Mode)

Automatically recompile Sass files on change:

compass watch

Keeps running; press Ctrl+C to stop.

One-time Compilation

compass compile

Add --force to recompile all files even if unchanged.

Validate Syntax

compass validate

Using with Existing Projects

If you already have Sass files, initialize Compass in your project directory:

compass init

Then adjust config.rb paths to match your existing structure.

5. Deployment

Compass is a build-time tool; it compiles Sass to CSS. Deployment involves:

1. Compile CSS for production (locally or in CI):

   compass compile --output-style compressed --force
   

   Sets output_style = :compressed in config.rb for production builds.

2. Deploy compiled CSS (from css_dir, default stylesheets/) along with your HTML/application to any static hosting:

   • Static hosts: Netlify, Vercel, GitHub Pages, S3 + CloudFront
   • Traditional servers: Apache, Nginx (copy CSS to public directory)
   • App platforms: Heroku, Render, AWS Elastic Beanstalk (include in buildpack)

3. CI/CD Integration (example for GitHub Actions):

   - name: Compile Sass
     run: |
       gem install compass
       compass compile --output-style compressed
   

6. Troubleshooting

"Compass is not recognized..." / "command not found"

• Ruby's gem bin directory not in PATH. Add ~/.gem/ruby/X.X.0/bin (Linux/macOS) or C:\RubyXX\bin (Windows) to PATH.
• Or use ruby -S compass from project directory.

Native Extension Build Failures

• Linux: Install build tools and libraries:

  sudo apt-get install build-essential libxml2-dev libxslt1-dev
  

• macOS: Install Xcode Command Line Tools.
• Windows: Ensure Ruby DevKit is properly installed and initialized.

Sass Syntax Errors

Compass uses the legacy sass Ruby gem (not Dart Sass). Ensure your Sass syntax is compatible (Compass primarily supports Sass 3.2-3.4 syntax). Avoid modern Sass features like @use/@forward.

"File to import not found or unreadable"

• Check sass_dir path in config.rb.
• Ensure Compass extensions (like compass-normalize) are installed: gem install compass-normalize.
• Use @import "compass"; only if Compass core is installed.

Deprecation Warnings

Since Compass is unmaintained, you may see warnings about deprecated Sass features. These usually still compile but consider migrating away from Compass long-term.

Permission Errors on gem install

Use a Ruby version manager (rbenv/RVM) instead of sudo, or configure gem installation to user directory:

gem install compass --user-install

Slow Compilation

• Disable line_comments in production.
• Use --quiet flag to suppress output.
• Split large Sass files into partials (_partial.scss).