birkmann/gulp-ruby-sass

Compile Sass to CSS with Ruby Sass

gulp-ruby-sass

Compiles Sass with the Sass gem.
To compile Sass with libsass, use gulp-sass

Install

You must have Sass >=3.4.

$ npm install --save-dev gulp-ruby-sass

Important!

• gulp-ruby-sass is a gulp source adapter. Use it instead of gulp.src.
• Since it's a source adapter you need to catch errors on the stream itself instead of using a package like plumber. See the Usage section for examples.
• gulp-ruby-sass doesn't support globs yet, only single files or directories. Just like Sass.
• gulp-ruby-sass doesn't support incremental builds yet (issue).
• gulp-ruby-sass doesn't alter Sass's output in any way. Problems with Sass output should be reported to the Sass issue tracker.

Usage

Use gulp-ruby-sass instead of gulp.src to compile a file or directory.

var gulp = require('gulp');
var sass = require('gulp-ruby-sass');

gulp.task('sass', function () {
	return sass('source/')
		.on('error', function (err) {
			console.error('Error!', err.message);
		})
		.pipe(gulp.dest('result'));
});

Recompiling on changes

Use gulp-watch to automatically recompile your files on change.

Handling errors

Handle Sass errors with an on('error', cb) listener. gulp-ruby-sass throws errors like a gulp plugin, but streams the erroring files so you can see Sass errors in your browser too.

Plugin options

verbose

Type: boolean
Default: false

Gives some extra information for debugging, including the actual spawned Sass command.

bundleExec

Type: boolean
Default: false

Run sass with bundle exec.

sourcemap

Type: boolean
Default: false

Requires Sass >=3.4 and gulp-sourcemaps.

Inline sourcemaps are recommended, as they "just work".

var gulp = require('gulp');
var sass = require('gulp-ruby-sass');
var sourcemaps = require('gulp-sourcemaps');

gulp.task('sass', function () {
	return sass('source', {sourcemap: true})
		.on('error', function (err) {
			console.error('Error!', err.message);
		})
		.pipe(sourcemaps.write())
		.pipe(gulp.dest('result'));
});

File sourcemaps require you to serve the sourcemap location so the browser can read the files. See the gulp-sourcemaps readme for more info.

gulp.task('sass', function() {
	return sass('source', { sourcemap: true })
	.on('error', function (err) {
	  console.error('Error', err.message);
   })

	.pipe(sourcemaps.write('maps', {
		includeContent: false,
		sourceRoot: '/source'
	}))

	.pipe(gulp.dest('result'));
});

container

Type: String
Default: gulp-ruby-sass

Name of the temporary directory used to process files. If you're running multiple instances of gulp-ruby-sass at once, specify a separate container for each task to avoid files mixing together.

var gulp = require('gulp');
var sass = require('gulp-ruby-sass');

gulp.task('sass-app', function () {
	return sass('source/app.scss', {container: 'gulp-ruby-sass-app'})
		.on('error', function (err) {
			console.error('Error!', err.message);
		})
		.pipe(gulp.dest('result/app'));
});

gulp.task('sass-site', function () {
	return sass('source/site.scss', {container: 'gulp-ruby-sass-site'})
		.on('error', function (err) {
			console.error('Error!', err.message);
		})
		.pipe(gulp.dest('result/site'));
});

gulp.task('sass', ['sass-app', 'sass-site']);

Sass options

Any other options are passed directly to the Sass executable. The options are camelCase versions of Sass's dashed-case options.

The docs below list common options for convenience. Run sass -h for the complete list.

loadPath

Type: string, array
Default: false

Import paths.

require

Type: string
Default: false

Require a Ruby library before running Sass.

compass

Type: boolean
Default: false

Make Compass imports available and load project configuration.

style

Type: string
Default: nested

Output style. Can be nested (default), compact, compressed, or expanded.

force

Type: boolean
Default: false

Recompile every Sass file, even if the CSS file is newer.

stopOnError

Type: boolean
Default: false

If a file fails to compile, exit immediately.

defaultEncoding

Type: string
Default: false

Specify the default encoding for input files.

unixNewlines

Type: boolean
Default: false

Use Unix-style newlines in written files on non-Unix systems. Always true on Unix.

debugInfo

Type: boolean
Default: false

Emit output that can be used by the FireSass Firebug plugin.

lineNumbers

Type: boolean
Default: false

Emit comments in the generated CSS indicating the corresponding source line.

check

Type: boolean
Default: false

Just check syntax, don't evaluate.

precision

Type: number
Default: 5

How many digits of precision to use when outputting decimal numbers.

cacheLocation

Type: string
Default: false

The path to save parsed Sass files. Defaults to .sass-cache.

noCache

Type: boolean
Default: false

Don't cache parsed Sass files.

trace

Type: boolean
Default: false

Show a full Ruby stack trace on error.

quiet

Type: boolean
Default: false

Silence warnings and status messages during compilation.

License

MIT © Sindre Sorhus