grunt-sass

Compile SCSS to CSS using node-sass

Bugs with the output should be submitted on the libsass repo which is the actual compiler.
Make sure to review its issue tracker for known bugs before using this task as it can bite you later on.

Overview

This task uses the experimental and superfast Node.js based Sass compiler node-sass (which only compiles .scss files).

Note that node-sass is currently under heavy development and might be unstable, there are also some stuff missing, like a compression option. Check out grunt-contrib-sass (based on Ruby Sass) if you want something stable that also supports the old syntax, but in turn much slower.

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, install this plugin with this command:

npm install --save-dev grunt-sass

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

grunt.loadNpmTasks('grunt-sass');

Tip: the load-grunt-tasks module makes it easier to load multiple grunt tasks.

Documentation

See the Gruntfile in this repo for a full example.

Note: Files that begin with "_" are ignored even if they match the globbing pattern. This is done to match the expected Sass partial behaviour.

Options

includePaths

Type: Array
Default: []

Import paths to include.

outputStyle

Type: String
Default: nested
Values: 'nested', 'expanded', 'compact', 'compressed'

Specify the CSS output style.

According to the node-sass documentation, there is currently a problem with lib-sass so this option is best avoided for the time being.

sourceComments

Type: String
Default: 'none'
Values: 'none', 'normal', 'map'

Set what debug information is included in the output file. The map option will create the source map file in your CSS destination.

sourceMap

Type: String

If your sourceComments option is set to map, sourceMap allows setting a new path context for the referenced Sass files. The source map describes a path from your CSS file location, into the the folder where the Sass files are located. In most occasions this will work out-of-the-box but, in some cases, you may need to set a different output.

Example config

grunt.initConfig({
	sass: {									// Task
		dist: {								// Target
			files: {						// Dictionary of files
				'main.css': 'main.scss'		// 'destination': 'source'
			}
		},
		dev: {								// Another target
			options: {						// Dictionary of render options
				includePaths: [
					'path/to/imports/'
				]
			},
			files: {
				'main.css': 'main.scss'
			}
		}
	}
});

grunt.loadNpmTasks('grunt-sass');
grunt.registerTask('default', ['sass']);

Example usage

Compile

grunt.initConfig({
	sass: {
		dist: {
			files: {
				'main.css': 'main.scss'
			}
		}
	}
});

Compile with options

grunt.initConfig({
	sass: {
		dist: {
			options: {
				includePaths: ['imports/are/here/'],
				outputStyle: 'nested'
			},
			files: {
				'main.css': 'main.scss'
			}
		}
	}
});

Compile multiple files

You can also compile multiple files into multiple destinations.

grunt.initConfig({
	sass: {
		files: {
			'main.css': 'main.scss',
			'widgets.css': 'widgets.scss'
		}
	}
});

dgieselaar / grunt-sass