Since Compass v0.12, this adapter is the only way to install compass into your rails application.
This adapter supports rails versions 2.3 and greater. Rails 2.3 and 3.0 users please read the caveats below.
compass-rails gem line to a group called
:assets in your application's Gemfile (Rails 3.1+ users should already have the
group :assets do gem 'compass-rails' end
If you are using any Compass extensions, add them to this group in your Gemfile.
And then execute:
To set up your project with starter stylesheets and a configuration file:
$ bundle exec compass init
$ bundle exec compass init --using blueprint
Note that the
compass init step is optional if you have a project running Rails 3.0 or greater.
Upgrading existing rails projects using Compass to CompassRails
First and foremost, follow the installation instructions above.
CompassRails uses the rails convention for stylesheet locations even in
older versions of rails that do not use the assets pipeline.
If you have your stylesheets already in
app/stylesheets, you have two choices:
- Move your stylesheets to
- Configure your project to look in
config.compass.sass_dir = "app/stylesheets"in your rails configuration or by setting
sass_dir = "app/stylesheets"in your compass configuration file.
If you have a compass configuration file (recommended) then you can
use the Compass configuration
as is. If you choose to configure compass from your rails configuration
files, then you should understand that the compass configuration
options explained there will be methods and properties on the
configuration object exposed to rails within any configuration block.
Developing with Rails-based Compilation
When using this approach you will need to reload your webpage in order to trigger a recompile of your stylesheets.
Developing with the Compass watcher
When using the Compass watcher to update your stylesheets, your stylesheets are recompiled as soon as you save your Sass files. In this mode, compiled stylesheets will be written to your project's public folder and therefore will be served directly by your project's web server -- superceding the normal rails compilation.
In this mode, rails 3.0 or earlier users will experience a slight
speed up by disabling the
Sass::Plugin like so:
config.after_initialize do Sass::Plugin.options[:never_update] = true end
To return to using the Rails-based compilation mode, simply delete the compiled stylesheets and remove any configuration changes.
Compiling for Production
If using the Rails asset pipeline run:
$ rake assets:precompile
If not using the asset pipeline run:
$ bundle exec compass compile -e production --force
It is suggested that you compile your stylesheets as part of the deploy or build process. However, some people choose to check in their compiled stylesheets.
Installing Compass extensions
Step 1: If the extension is a rubygem, Add it to your Gemfile in the
:assets group and run the
bundle command to install it.
If the extension is a zip file, unzip it into the
vendor/plugins/compass_extensions directory of your project.
Step 2: Install the extension's assets:
bundle exec compass install
For example, if you want to use susy.
# Gemfile group :assets do gem 'compass-rails' gem 'compass-susy-plugin' end
$ bundle $ bundle exec compass install susy
Notes On Sprockets Directives
Sprockets, used by the rails asset pipeline, provides directives for
doing things like requiring. These must not be used with Sass files.
Instead use the sass
@import directive. In rails projects, the
@import directive is configured to work with sprockets via
sass-rails. For more information on importing in rails 3.1 or greater see the Sass-Rails REAME
Rails 3.0 Caveats
If you want rails to compile your stylesheets (instead of using the
compass watcher) you need to edit
config/application.rb and change:
Bundler.require(:default, Rails.env) if defined?(Bundler)
Bundler.require(:default, :assets, Rails.env) if defined?(Bundler)
Rails 2.3 Caveats
Compass requires that your rails 2.3 project is using Bundler to manage your rubygems. If you haven't yet set up your rails 2.3 project to use Bundler, please do so prior to upgrading. Bundler installation guide for rails 2.3.
After following the instructions there, if you want rails to compile
your stylesheets (instead of using the compass watcher) you need
config/boot.rb and change this:
Rails::Initializer.class_eval do def load_gems @bundler_loaded ||= Bundler.require :default, Rails.env end end
Rails::Initializer.class_eval do def load_gems @bundler_loaded ||= Bundler.require :default, :assets, Rails.env end end
- Fork it
- Create your feature branch (
git checkout -b my-new-feature)
- Commit your changes (
git commit -am 'Added some feature')
- Push to the branch (
git push origin my-new-feature)
- Create new Pull Request