gulp-scss

1.4.0 verified Fri May 01 auth: no javascript deprecated

Gulp plugin for compiling SCSS (SASS) using the standard `scss` command-line tool or via `bundle exec scss`. Current stable version is 1.4.0. The plugin is explicitly noted as obsolete by the author because libsass (used by gulp-sass) now matches Ruby Sass features. It passes options via dargs, supports temporary file caching, and allows globbing (unlike gulp-ruby-sass). Not recommended for new projects; use gulp-sass (node-sass) or gulp-dart-sass instead.

Common errors

error Error: spawn scss ENOENT ↓

cause Ruby Sass (or `scss` command) is not installed on the system.

fix

Install Ruby Sass: gem install sass, or use bundleExec: true and ensure bundle is available.

error TypeError: scss is not a function ↓

cause Incorrect import style; using named import instead of default.

fix

Use import scss from 'gulp-scss' (default import) instead of destructuring.

error Options passed to dargs produce invalid command line ↓

cause Complex options (e.g., loadPath as array) may not serialize correctly.

fix

Flatten options into string-typed CLI flags, or use gulp-sass which supports object options.

Warnings

deprecated This package is obsolete. Use gulp-sass (node-sass) or gulp-dart-sass instead. ↓

fix Replace gulp-scss with gulp-sass and adjust your configuration.

gotcha Options are passed via dargs: boolean options like sourcemap become --sourcemap without value—might cause unexpected behavior. ↓

fix Ensure options are in format suitable for CLI flags; test command generation.

gotcha Requires Ruby Sass or `bundle exec scss` installed system-wide; not a pure Node.js solution. ↓

fix If not available, install Ruby Sass or use bundle exec with a Gemfile.

deprecated The `gulp-util` dependency is deprecated and may cause peer-dep warnings. ↓

fix Consider migrating to gulp-sass or another maintained plugin.

Install

npm install gulp-scss

yarn add gulp-scss

pnpm add gulp-scss

Imports

gulpScss
wrong
```
const gulpScss = require('gulp-scss')
```
correct
```
import gulpScss from 'gulp-scss'
```
Default import. The plugin is a function that takes options.
gulp
wrong
```
const gulp = require('gulp')
```
correct
```
import gulp from 'gulp'
```
gulp itself is a separate dependency, but commonly used together.

scss

wrong

const { scss } = require('gulp-scss')

correct

import scss from 'gulp-scss'

Named export does not exist; use default import.

Quickstart

Shows basic gulp task that compiles SCSS files using gulp-scss with bundle exec and custom temp path.

import gulp from 'gulp';
import scss from 'gulp-scss';

gulp.task('scss', function() {
  return gulp.src('src/**/*.scss')
    .pipe(scss({
      bundleExec: true,
      tmpPath: '.temp-cache'
    }))
    .pipe(gulp.dest('dist/css'));
});