Compile Sass to CSS using Compass
Last updated 4 years ago by vladikoff .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install grunt-contrib-compass 
SYNC missed versions from official npm registry.

grunt-contrib-compass v1.1.1 Build Status: Linux

Compile Sass to CSS using Compass

Getting Started

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-contrib-compass --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:


Compass task

Run this task with the grunt compass command.

Compass is an open-source authoring framework for the Sass css preprocessor. It helps you build stylesheets faster with a huge library of Sass mixins and functions, advanced tools for spriting, and workflow improvements including file based Sass configuration and a simple pattern for building and using Compass extensions.

This task requires you to have Ruby, Sass, and Compass >=1.0.1 installed. If you're on OS X or Linux you probably already have Ruby installed; test with ruby -v in your terminal. When you've confirmed you have Ruby installed, run gem update --system && gem install compass to install Compass and Sass.

Compass operates on a folder level. Because of this you don't specify any src/dest, but instead define the sassDir and cssDir options.


Compass doesn't expose all of its options through the CLI, which this task makes use of. If you need an option not mentioned below you can either specify a path to a config.rb file in the config option or embed it directly into the raw option. Options defined in your Gruntfile will override those specified in your config.rb or raw property. config and raw are mutually exclusive.


Type: Boolean
Default: false

Generate Source Maps.


Type: String
Default: same path as your Gruntfile

Specify the location of the Compass configuration file explicitly.


Type: String

String form of the Compass configuration file.


Type: String

The path Compass will run from. Defaults to the same path as your Gruntfile.


Type: String

Prepend the specified string to the output file. Useful for licensing information. Note: This only works in combination with the specify option and can conflict with sourcemap generation.


Type: String
Default: stand_alone

Tell compass what kind of application it is integrating with. Can be stand_alone or rails.


Type: String

The source directory where you keep your Sass stylesheets.


Type: String

The target directory where you keep your CSS stylesheets.


Type: String|Array

Lets you specify which files you want to compile. Useful if you don't want to compile the whole folder. Globbing supported. Ignores filenames starting with underscore. Paths are relative to the Gruntfile.


Type: String

The directory where you keep your images.


Type: String

The directory where you keep your JavaScript files.


Type: String

The directory where you keep your fonts.


Type: String
Default: development

Use sensible defaults for your current environment. Can be: development or production


Type: String

CSS output mode. Can be: nested, expanded, compact, compressed.


Type: Boolean

Make Compass asset helpers generate relative urls to assets.


Type: Boolean

Disable line comments.


Type: String
Default: /

The path to the project when running within the web server.


Type: String

The directory where the css stylesheets are kept. It is relative to the projectPath. Defaults to "stylesheets".


Type: String
Default: httpPath + "/" + cssDir

The full http path to stylesheets on the web server.


Type: String
Default: sass

The directory where the sass stylesheets are kept. It is relative to the projectPath.


Type: String
Default: images

The directory where the images are kept. It is relative to the projectPath.


Type: String
Default: httpPath + "/" + imagesDir

The full http path to images on the web server.


Type: String
Default: value of imagesDir

The directory where generated images are kept. It is relative to the projectPath.


Type: String
Default: value of projectPath/generatedImagesDir

The full path to where generated images are kept.


Type: String
Default: httpPath + "/" + generatedImagesDir

The full http path to generated images on the web server.


Type: String|Array
Default: value of imagesPath

Add additional locations to look for sprites. The imagesPath is always the last entry in this list.


Type: String
Default: projectPath/javascriptsDir

The full path to where javascripts are kept.


Type: String
Default: httpPath + "/" + javascriptsDir

The full http path to javascripts on the web server.


Type: String
Default: projectPath/fontsDir

The full path to where font files are kept.


Type: String

The full http path to font files on the web server.


Type: String

The relative http path to font files on the web server.


Type: String
Default: project_root/extensions

The full http path to the ad-hoc extensions folder on the web server. This is used to access compass plugins that have been installed directly to the project (e.g. through Bower) instead of globally as gems. Only Compass >=0.12.2


Type: String

The relative http path to the ad-hoc extensions folder on the web server. Only Compass >=0.12.2


Type: Boolean
Default: true

If set to false, this disables the default asset cache buster.


Type: String
Default: .sass-cache

The relative path to the folder where the sass cache files are generated.


Type: String|Array

Require the given Ruby library before running commands. This is used to access Compass plugins without having a project configuration file.


Type: String|Array

Load the framework or extensions found in the specified directory.


Type: String|Array

Load all the frameworks or extensions found in the specified directory.


Type: String|Array

Makes files under the specified folder findable by Sass's @import directive.


Type: Boolean

Causes the line number and file where a selector is defined to be emitted into the compiled CSS in a format that can be understood by the browser. Automatically disabled when using outputStyle: 'compressed'.


Type: Boolean

Quiet mode.


Type: Boolean

Show a full stacktrace on error.


Type: Boolean

Allows Compass to overwrite existing files.


Type: Boolean

Turn off colorized output.


Type: Boolean

Run compass compile with bundle exec: bundle exec compass compile.


Type: Boolean

Remove generated files and the sass cache. Runs compass clean instead of compass compile.


Type: Boolean

Runs compass watch instead of compass compile. This will use Compass' native watch command to listen for changes to Sass files and recompile your CSS on changes. While much faster than running compass compile each time you want to compile your Sass, Compass becomes a blocking task. This means that if you would like to use it in conjunction with another blocking task, such as watch, you will need to use it in conjunction with a paralleling task such as grunt-concurrent.

Usage Examples

Example config

  compass: {                  // Task
    dist: {                   // Target
      options: {              // Target options
        sassDir: 'sass',
        cssDir: 'css',
        environment: 'production'
    dev: {                    // Another target
      options: {
        sassDir: 'sass',
        cssDir: 'css'


grunt.registerTask('default', ['jshint', 'compass']);

Example usage

Use external config file
  compass: {
    dist: {
      options: {
        config: 'config/config.rb'
Override setting in external config file
  compass: {
    dist: {
      options: {
        config: 'config/config.rb',  // css_dir = 'dev/css'
        cssDir: 'dist/css'
Use raw option
  compass: {
    dist: {
      options: {
        sassDir: 'sass',
        cssDir: 'css',
        raw: 'preferred_syntax = :sass\n' // Use `raw` since it's not directly available

Release History

  • 2016-03-04   v1.1.1   pass only compass package name, not full path
  • 2016-02-15   v1.1.0   Use which to find compass binary cross platform. Update async and tmp dependencies.
  • 2015-09-29   v1.0.4   Use the compass flag for the httpPath option. Use single-quotes in the config.rb generated file.
  • 2015-04-02   v1.0.3   Add --config path before -- option/argument separator.
  • 2015-03-31   v1.0.2   Improve POSIX compliance.
  • 2014-09-08   v1.0.1   Use compass long flag for importPath
  • 2014-09-05   v1.0.0   Fix bundleExec option on Windows.
  • 2014-07-31   v0.9.1   Fixes npm peerDependency warnings.
  • 2014-06-24   v0.9.0   Add Compass version check to ensure only a supported version is used.
  • 2014-05-16   v0.8.0   Add spriteLoadPath option.
  • 2014-02-09   v0.7.2   Improve compatibility with Compass 0.13.
  • 2014-01-26   v0.7.1   Fix assetCacheBuster option.
  • 2013-12-07   v0.7.0   Add cacheDir option.
  • 2013-10-04   v0.6.0   Add watch option. Fix Compass errors not propagating.
  • 2013-08-08   v0.5.0   Add assetCacheBuster option.
  • 2013-07-28   v0.4.1   Fix banner option with .css.scss files.
  • 2013-07-19   v0.4.0   Add banner option. Show compilation time.
  • 2013-06-24   v0.3.0   Add extensionDir and extensionPath options. Requires Compass >=0.12.2.
  • 2013-04-11   v0.2.0   Add clean option. Expose raw options as Grunt options. Fix detection of Nothing to compile situation.
  • 2013-02-27   v0.1.3   Fixes bundleExec.
  • 2013-02-17   v0.1.2   Ensure Gruntfile.js is included on npm.
  • 2013-02-15   v0.1.1   First official release for Grunt 0.4.0.
  • 2013-02-05   v0.1.1rc8   Added new options: basePath specify, debugInfo.
  • 2013-01-25   v0.1.1rc7   Updating grunt/gruntplugin dependencies to rc7. Changing in-development grunt/gruntplugin dependency versions from tilde version ranges to specific versions.
  • 2013-01-10   v0.1.1rc5   Updating to work with grunt v0.4.0rc5.
  • 2012-10-22   v0.1.0   Initial release

Task submitted by Sindre Sorhus

This file was generated on Fri Mar 04 2016 16:24:46.

Current Tags

  • 1.1.1                                ...           latest (4 years ago)

25 Versions

  • 1.1.1                                ...           4 years ago
  • 1.1.0                                ...           4 years ago
  • 1.0.4                                ...           5 years ago
  • 1.0.3                                ...           5 years ago
  • 1.0.2                                ...           5 years ago
  • 1.0.1                                ...           6 years ago
  • 1.0.0                                ...           6 years ago
  • 0.9.1                                ...           6 years ago
  • 0.9.0                                ...           6 years ago
  • 0.8.0                                ...           6 years ago
  • 0.7.2                                ...           6 years ago
  • 0.7.1                                ...           6 years ago
  • 0.7.0                                ...           7 years ago
  • 0.6.0                                ...           7 years ago
  • 0.5.0                                ...           7 years ago
  • 0.4.1                                ...           7 years ago
  • 0.4.0                                ...           7 years ago
  • 0.3.0                                ...           7 years ago
  • 0.2.0                                ...           7 years ago
  • 0.1.3                                ...           7 years ago
  • 0.1.2                                ...           7 years ago
  • 0.1.1                                ...           7 years ago
  • 0.1.1-rc8                                ...           6 years ago
  • 0.1.1-rc7                                ...           6 years ago
  • 0.1.0                                ...           8 years ago
Today 1
This Week 1
This Month 181
Last Day 9
Last Week 106
Last Month 429
Dependencies (6)
Dev Dependencies (7)

Copyright 2014 - 2016 © |