stylelint-sass-render-errors

4.1.3 verified Fri May 01 auth: no javascript

A Stylelint plugin (v4.1.3) that displays Sass render errors and deprecations as lint errors. It integrates the Sass compiler (Dart Sass) into Stylelint, treating deprecations as errors to encourage code modernization. Unlike other Sass linting tools, it operates per file and supports modern Sass APIs (`compile`, `compileString`) with options for sync/async rendering, custom Sass options, and undefined function checking. Requires Node >=18.12, Stylelint >=14, and Dart Sass (peer dependency). Released actively with monthly or quarterly updates.

Common errors

error Error: You gave us a `require` call, but this is an ES module. Please use `import` instead. ↓

cause Using CommonJS require() with ESM-only package (v4+).

fix

Use ES module import syntax or convert your project to ESM.

error SyntaxError: Named export 'default' not found. The requested module 'stylelint-sass-render-errors' is a CommonJS module; it may need a default import. ↓

cause Incorrect import syntax when using the plugin programmatically.

fix

Use import stylelintSassRenderErrors from 'stylelint-sass-render-errors' (default import) or use plugin config as string.

error Unknown rule: plugin/sass-render-errors ↓

cause Plugin not loaded in Stylelint config.

fix

Add the plugin to the plugins array in .stylelintrc: "plugins": ["stylelint-sass-render-errors"].

Warnings

breaking v4.0.0 dropped CommonJS support; only ESM is supported. ↓

fix Use import syntax or update Node.js to >=18.12 and ensure your project uses ESM.

breaking v4.0.0 dropped support for Node <18.12 and Dart Sass <1.75. ↓

fix Upgrade Node to >=18.12 and Dart Sass to >=1.75.

breaking v4.0.0 uses the new Sass JS API (compile/compileString) instead of the deprecated render. ↓

fix Ensure your Sass options are compatible with the new API; see Sass docs.

deprecated The 'render' method is deprecated in Dart Sass 1.75+ and removed in later versions; plugin v4+ uses 'compile'. ↓

fix Use the new API; no action needed if using the plugin as-is.

gotcha Global @import statements are not supported; the plugin operates per file. ↓

fix Switch to Sass modules (@use/@forward) for better isolation.

gotcha Undefined function checking is off by default; you must explicitly enable checkUndefinedFunctions. ↓

fix Set checkUndefinedFunctions: true in plugin options.

Install

npm install stylelint-sass-render-errors

yarn add stylelint-sass-render-errors

pnpm add stylelint-sass-render-errors

Imports

stylelint-sass-render-errors (plugin)
wrong
```
plugins: ['stylelint-sass-render-errors/index.js']
```
correct
```
plugins: ['stylelint-sass-render-errors']
```
In Stylelint config, reference the package name directly; no explicit import required in JS files.
rule 'plugin/sass-render-errors'
wrong
```
rules: { 'sass-render-errors': true }
```
correct
```
rules: { 'plugin/sass-render-errors': true }
```
Rule names must be prefixed with 'plugin/' as per Stylelint plugin convention.

ESM import (if used programmatically)

wrong

const stylelintSassRenderErrors = require('stylelint-sass-render-errors');

correct

import stylelintSassRenderErrors from 'stylelint-sass-render-errors';
stylelint.createPlugin(stylelintSassRenderErrors);

Since v4.0.0, the package is ESM-only; CommonJS require() will fail.

Quickstart

Configures the plugin to catch Sass deprecations and undefined functions, then lint an SCSS file.

// .stylelintrc.json
{
  "plugins": ["stylelint-sass-render-errors"],
  "rules": {
    "plugin/sass-render-errors": [true, {
      "sync": false,
      "sassOptions": { "style": "expanded" },
      "checkUndefinedFunctions": true,
      "disallowedKnownCssFunctions": ["lighten", "darken"],
      "additionalKnownCssFunctions": []
    }]
  }
}

// Example SCSS that triggers an error:
// _test.scss
@use 'sass:color';
.foo {
  color: color.invert(1); // passing number to invert() is deprecated
}

// Run stylelint on the file:
// npx stylelint _test.scss