Sass Lint

1.13.1 verified Sat Apr 25 auth: no javascript maintenance

A Node-only Sass linter for both .sass and .scss syntax, providing over 70 configurable rules for code quality and consistency. Current stable version is 1.13.1, which reverts breaking changes from the mistakenly released 1.13.0 (which introduced a new AST parser and disabled-next-line feature). Development has slowed significantly since 2019, with no recent releases. Key differentiators include extensive configurability via YAML/JSON, a migration tool from SCSS-Lint, and performance-focused cache options. However, it has known issues with modern Sass syntax and is largely superseded by stylelint with scss plugins.

Common errors

error Error: Cannot find module 'gonzales-pe-sl' ↓

cause Missing dependency after npm install due to package.json not including it in dependencies explicitly (it's a fork).

fix

Run: npm install gonzales-pe-sl@1.0.0 --save-dev

error Unexpected token: ... at line X, col Y (SCSS parsing error) ↓

cause sass-lint's parser does not support certain modern Sass syntax (e.g., @use, @forward, slash-division).

fix

Use stylelint with stylelint-scss instead, or avoid unsupported syntax and downgrade to Sass 3.x.

error SassLint: Unknown option: 'formatter' in config ↓

cause Invalid config key; the correct key is 'options.formatter' not top-level 'formatter'.

fix

Move 'formatter' inside 'options' block in the config file or use CLI flag: sass-lint -f stylish

error sass-lint: No files to lint ↓

cause Glob pattern in 'files.include' does not match any files or is misconfigured.

fix

Check that the glob pattern is correct and files exist. Example: files.include: '**/*.s+(a|c)ss'

Warnings

breaking v1.13.0 was mistakenly released with breaking changes (new AST parser) and should have been a major version. v1.13.1 reverts to match v1.12.1 behavior. ↓

fix Use v1.13.1 or later, and ensure config does not rely on any 1.13.0-specific features (e.g., disable-next-line may not work as expected).

deprecated Package is effectively unmaintained since 2019; no bug fixes or Sass syntax updates for newer features like @use, @forward, or module system. ↓

fix Migrate to stylelint with stylelint-scss plugin for ongoing support.

gotcha The CLI does not exit with non-zero code on warnings by default unless --no-exit flag is omitted; use --no-exit -q to suppress errors. ↓

fix Run with command: sass-lint --no-exit -q -c .sass-lint.yml

gotcha Some rules (e.g., indentation) may produce false positives with nested @at-root or advanced selector patterns. ↓

fix Disable problematic rules in config or adjust file patterns to exclude known edge cases.

deprecated Rule 'no-color-keywords' flags custom properties containing color names (e.g., --blue) as errors. This was fixed in v1.12.0 but still may have edge cases. ↓

fix Update to v1.12.1+ or configure the rule to ignore custom properties.

Install

npm install sass-lint

yarn add sass-lint

pnpm add sass-lint

Imports

sassLint

wrong

import sassLint from 'sass-lint';

correct

const sassLint = require('sass-lint');

Package is CJS-only, no ESM exports. Use require().

lintFiles

wrong

import { lintFiles } from 'sass-lint';

correct

const { lintFiles } = require('sass-lint');

Named export available via CJS destructuring.

lintText

wrong

import lintText from 'sass-lint';

correct

const { lintText } = require('sass-lint');

Use named export for inline linting.

outputResults

wrong

const outputResults = require('sass-lint').outputResults;

correct

const { outputResults } = require('sass-lint');

Same pattern, but ensure destructuring matches.

Quickstart

Basic example showing how to lint files and inline text using the Node API, with callback and output formatting.

const { lintFiles, lintText } = require('sass-lint');

// Lint a file
const results = lintFiles('path/to/file.scss', {
  configFile: '.sass-lint.yml',
  options: { formatter: 'stylish' }
});

// Lint a string
const textResults = lintText('.class { color: red; }', {
  filename: 'inline.scss',
  options: { syntax: 'scss' }
}, (err, data) => {
  if (err) throw err;
  console.log(data.warningCount + ' warnings');
});

// Output results
const { outputResults } = require('sass-lint');
outputResults(results, 'stylish');