Compass with Serve and Rack

I talked briefly about racking up your Serve projects in my previous article. But apart from the benefit of being able to deploy Serve on Passenger or Mongrel, why is Rack integration cool?

One benefit is that you get access to all kinds of middleware. Middleware is a software module that extends your server or web application with additional functionality. It’s called middleware because it sits between your application and the web server software. When a request for a file or resource comes into the server it first travels through each layer of middleware before reaching your application. Your application then sends a response back which again travels each layer of middleware before being served up to the user. As the request and response travel through each layer of middleware, the middleware can make changes to or even serve up something totally different. This is useful for adding features like logging, custom error handling, or gzip compression.

I my original article I showed you how to use Rack::ShowStatus and Rack::ShowExceptions to get handy error messages for your project. Today, I’d like to show you how to add Compass integration.

Never heard of Compass? Compass is a fancy new CSS framework built on Sass and it’s awesome. Among other things it provides a number of handy CSS3 modules that allow you to easily use a number of advanced CSS features. Without Compass and Sass this kind of stuff becomes pretty labor intensive to write.

Now Serve comes with built in support for serving Sass files, but it doesn’t know anything about Compass. To use Serve with Compass you will need to add the following lines to your config.ru file:

require 'sass/plugin/rack'
require 'compass'

Compass.add_project_configuration(root + '/compass.config')
Compass.configure_sass_plugin!
use Sass::Plugin::Rack # Compile Sass on the fly

The first two lines are necessary so that the Sass Rack middleware is installed and the Compass framework is loaded. The next two lines tell Compass where your configuration file is located (in this case I’ve put it in the project root) and configure Sass using the configuration values stored there. The last line loads the Sass plugin as middleware.

Your compass.config should look something like this:

http_path       = "/"
css_dir = "public/stylesheets"
sass_dir = "public/stylesheets/sass"
images_dir = "images"
javascripts_dir = "javascripts"
relative_assets = false

Your actual values will vary depending on how you are using Compass, but the key variables for the purposes of this tutorial are css_dir and sass_dir. In this case I’ve chosen to have the plugin generate my CSS in the public/stylesheets directory and store my Sass (much like Rails does) in the public/stylesheets/sass directory.

If you’ve separated your dynamic and static assets into the views and public directories (like I suggested in my previous article) you will notice that I’ve chosen to put my Sass and CSS in the directory for static assets (public). This is because the Sass plugin is designed to generate your CSS when the first request is made to your Serve application. Generated files are nice in production environments because they can be served directly by the Web server instead of by your application. This is in contrast to the way that Sass files are normally used with a Serve project. Normally, you would put your Sass files in views/stylesheets and they would be processed by the Serve Rack adapter on each request.

Here’s a Gist of the source code for this entire tutorial along with a couple of other goodies. Enjoy!

Hat tip to Chris Eppstein for his help with this.

© 2013 John W. Long