grunt-scss-lint

0.5.0 verified Fri May 01 auth: no javascript deprecated

A Grunt plugin that wraps the Ruby scss-lint gem (scss_lint) to validate .scss files. Version 0.5.0 is the last release before deprecation; requires Ruby >= 1.9, scss_lint gem, and Grunt >= 0.4.0. Provides options like bundleExec, colorizeOutput, compact reporting, config, gemVersion, exclude, reporterOutput, emitError/emitSuccess, and failOnWarning. It runs the Ruby gem as a child process, so it's slower than pure JS linters like stylelint; it relies on an external Ruby dependency and is unmaintained.

Common errors

error Warning: Cannot find module 'grunt-scss-lint' Use --force to continue. ↓

cause Missing npm package installation or loadNpmTasks with wrong name.

fix

Run 'npm install grunt-scss-lint --save-dev' and ensure grunt.loadNpmTasks('grunt-scss-lint') is called.

error Warning: Cannot find scss-lint. Use --force to continue. ↓

cause The Ruby gem scss_lint is not installed or not in PATH.

fix

Install the gem: 'gem install scss_lint' or use bundleExec with Bundler.

error Fatal error: scss-lint exited with code 1. ↓

cause SCSS file has lint errors or warnings (and failOnWarning is true).

fix

Fix the reported issues in your .scss files or disable failOnWarning if warnings are acceptable.

error Warning: The --compact flag is not supported by your version of scss-lint. ↓

cause The installed scss_lint gem version does not support the compact output option.

fix

Set compact: false in options, or update the scss_lint gem to a compatible version.

Warnings

deprecated This plugin is unmaintained and deprecated. The scss-lint gem is also deprecated; use stylelint or Dart Sass instead. ↓

fix Migrate to stylelint with scss plugin: https://github.com/stylelint-scss/stylelint-scss

breaking Requires Ruby and scss_lint gem. If Ruby is not installed or the gem is missing, the task fails with 'Cannot find scss-lint'. ↓

fix Install Ruby and run 'gem install scss_lint' or ensure bundler is configured correctly.

breaking The gem was renamed from scss-lint to scss_lint. Older versions may try to execute the wrong command. ↓

fix Upgrade to version 0.3.7+ or set the 'gemVersion' option to avoid confusion.

gotcha On Windows, colorizeOutput requires extra gems (windows-pr, win32console). Output may be garbled if those are missing. ↓

fix Set colorizeOutput: false on Windows or install 'gem install windows-pr win32console'.

gotcha The 'config' option default points to a bundled YAML file inside node_modules. Override to use your own configuration. ↓

fix Explicitly set config: '.scss-lint.yml' in your Gruntfile options.

breaking By default, task fails on warnings (failOnWarning: true). Many users expect only errors to cause failure. ↓

fix Set failOnWarning: false in options to fail only on errors.

Install

npm install grunt-scss-lint

yarn add grunt-scss-lint

pnpm add grunt-scss-lint

Imports

grunt-scss-lint
wrong
```
require('grunt-scss-lint');
```
correct
```
grunt.loadNpmTasks('grunt-scss-lint');
```
This is a Grunt plugin, not a Node.js module. It is loaded via loadNpmTasks in Gruntfile, not required.

scsslint task

wrong

grunt.initConfig({ 'grunt-scss-lint': { ... } });

correct

grunt.initConfig({ scsslint: { all: { src: ['src/**/*.scss'] } } });

The task name is 'scsslint', not the package name. Configure it under the 'scsslint' key.

Options

wrong

scsslint: { config: '.scss-lint.yml', all: { ... } }

correct

scsslint: { options: { config: '.scss-lint.yml' }, all: { src: ['*.scss'] } }

Options must be nested under an 'options' key within the target or at the task level.

Quickstart

Basic Gruntfile configuration to lint all .scss files with scss-lint using the grunt-scss-lint plugin.

// Install: npm install grunt-scss-lint --save-dev
// In Gruntfile.js
module.exports = function(grunt) {
  grunt.loadNpmTasks('grunt-scss-lint');
  grunt.initConfig({
    scsslint: {
      all: {
        src: ['src/**/*.scss'],
        options: {
          config: '.scss-lint.yml',
          colorizeOutput: true,
          failOnWarning: true
        }
      }
    }
  });
  grunt.registerTask('default', ['scsslint']);
};