gulp-scss-lint

Lint your .scss files

Install

npm install gulp-scss-lint --save-dev

This plugin requires Ruby and scss-lint

gem install scss_lint

Usage

gulpfile.js

var scsslint = require('gulp-scss-lint');
 
gulp.task('scss-lint', function() {
  return gulp.src('/scss/*.scss')
    .pipe(scsslint());
});

Api

config

Type: String
Default: default scss-lint config file.

scsslint({
    'config': 'lint.yml'
});

bundleExec

Type: Boolean
Default: false

If your gem is installed via bundler, then set this option to true

scsslint({
    'bundleExec': true
});

reporterOutput

Type: String
Default: null

If you want to save the report to a file then set reporterOutput with a file name

scsslint({
    'reporterOutput': 'scssReport.json'
});

reporterOutputFormat

Type: String
Default: JSON
Values: JSON or Checkstyle

gulp.src(['**/*.scss'])
  .pipe(scsslint({
    'reporterOutputFormat': 'Checkstyle',
  }))

filePipeOutput

Type: String
Default: null

If you want the pipe return a report file instead of the .scss file then set filePipeOutput with a filename

//xml 
gulp.src(['**/*.scss'])
  .pipe(scsslint({
    'reporterOutputFormat': 'Checkstyle',
    'filePipeOutput': 'scssReport.xml'
  }))
  .pipe(gulp.dest('./reports'))
 
//json 
gulp.src(['**/*.scss'])
  .pipe(scsslint({
    'filePipeOutput': 'scssReport.json'
  }))
  .pipe(gulp.dest('./reports'))

maxBuffer

Type: Number or Boolean
Default: 300 * 1024

Set maxBuffer for the child_process.exec process. If you get a maxBuffer exceeded error, set it with a higher number. maxBuffer specifies the largest amount of data allowed on stdout or stderr.

gulp.src(['**/*.scss'])
  .pipe(scsslint({
    'maxBuffer': 307200
  }))
  .pipe(gulp.dest('./reports'))

endless

Type: Boolean
Default: false

If you use gulp-watch set endless to true.

sync

Type: Boolean
Default: sync

scss-lint will be executed in sequence.

verbose

Type: Boolean
Default: false

If you want to see the executed scss-lint command for debugging purposes, set this to true.

Glob pattern without gulp.src

var scsslint = require('gulp-scss-lint');
 
gulp.task('scss-lint', function() {
  return scsslint({
    shell: 'bash', // your shell must support glob 
    src: '**/*.scss'
  });
});

Excluding

To exclude files you should use the gulp.src ignore format '!filePath''

gulp.src(['/scss/*.scss', '!/scss/vendor/**/*.scss'])
  .pipe(scsslint({'config': 'lint.yml'}));

Or you should use gulp-filter

var scsslint = require('gulp-scss-lint');
var gulpFilter = require('gulp-filter');
 
gulp.task('scss-lint', function() {
  var scssFilter = gulpFilter('/scss/vendor/**/*.scss');
 
  return gulp.src('/scss/*.scss')
    .pipe(scssFilter)
    .pipe(scsslint())
    .pipe(scssFilter.restore());
});

Lint only modified files

You should use gulp-cached

In this example, without the gulp-cached plugin, every time you save a .scss file the scss-lint plugin will check all your files. In case you have gulp-cached plugin, it will only check the modified files.

var scsslint = require('gulp-scss-lint');
var cache = require('gulp-cached');
 
gulp.task('scss-lint', function() {
  return gulp.src('/scss/*.scss')
    .pipe(cache('scsslint'))
    .pipe(scsslint());
});
 
gulp.task('watch', function() {
  gulp.watch('/scss/*.scss', ['scss-lint']);
});

Results

Adds the following properties to the file object:

file.scsslint = {
  'success': false,
  'errors': 0,
  'warnings': 1,
  'issues': [
    {
      'line': 123,
      'column': 10,
      'severity': 'warning', // or `error` 
      'reason': 'a description of the error'
    }
  ]
};

The issues have the same parameters that scss-lint

Custom reporter

You can replace the default console log by a custom output with customReport. customReport function will be called for each file that includes the lint results See result params

var scsslint = require('gulp-scss-lint');
 
var myCustomReporter = function(file) {
  if (!file.scsslint.success) {
    gutil.log(file.scsslint.issues.length + ' issues found in ' + file.path);
  }
};
 
gulp.task('scss-lint', function() {
  return gulp.src('/scss/*.scss')
    .pipe(scsslint({
        customReport: myCustomReporter
    }))
});

You can even throw an exception

var scsslint = require('gulp-scss-lint');
 
var myCustomReporter = function(file, stream) {
  if (!file.scsslint.success) {
    stream.emit('error', new gutil.PluginError("scss-lint", "some error"));
  }
};
 
gulp.task('scss-lint', function() {
  return gulp.src('/scss/*.scss')
    .pipe(scsslint({
        customReport: myCustomReporter
    }))
});

Default reporter

This is an example from the default reporter output

[20:55:10] 3 issues found in test/fixtures/invalid.scss
[20:55:10] test/fixtures/invalid.scss:1 [W] IdSelector: Avoid using id selectors
[20:55:10] test/fixtures/invalid.scss:2 [W] Indentation: Line should be indented 2 spaces, but was indented 0 spaces
[20:55:10] test/fixtures/invalid.scss:2 [W] EmptyRule: Empty rule

Fail reporter

If you want the task to fail when "scss-lint" was not a success then call failReporter after the scsslint call.

This example will log the issues as usual and then fails if there is any issue.

var scsslint = require('gulp-scss-lint');
 
gulp.task('scss-lint', function() {
  return gulp.src('/scss/*.scss')
    .pipe(scsslint())
    .pipe(scsslint.failReporter())
});

if you just want failReporter to fail just with errors pass the 'E' string

var scsslint = require('gulp-scss-lint');
 
gulp.task('scss-lint', function() {
  return gulp.src('/scss/*.scss')
    .pipe(scsslint())
    .pipe(scsslint.failReporter('E'))
});

Testing

To test you must first have scss-lint installed globally using gem install scss_lint as well as via bundler using bundle install.

gulp-scss-lint

gulp-scss-lint

Install

Usage

Api

config

bundleExec

reporterOutput

reporterOutputFormat

filePipeOutput

maxBuffer

endless

sync

verbose

Glob pattern without gulp.src

Excluding

Lint only modified files

Results

Custom reporter

Default reporter

Fail reporter

Testing

Private packages for the whole team

Collaborators list

Stats

Try it out

Keywords

Dependencies (11)

Dependents (37)